RESTful API 是后端服务最通用的接口风格。本文以 Express 为例,从零搭建一套规范的 API 服务,涵盖路由设计、中间件、参数校验、错误处理等关键环节。读完即可上手自己的项目。
一、RESTful 设计风格要点
REST 不是协议,而是一种架构风格。它的核心是用 HTTP 动词表达操作意图,用 URL 表达资源。
GET /api/users— 获取用户列表GET /api/users/:id— 获取单个用户POST /api/users— 创建用户PUT /api/users/:id— 整体更新用户PATCH /api/users/:id— 部分更新DELETE /api/users/:id— 删除用户
URL 用名词复数,HTTP 动词表达动作。不要出现 /api/getUserList 这种动词式路径。
二、初始化练习工程
mkdir my-api && cd my-api
npm init -y
npm install express cors morgan helmet
npm install -D nodemon
几个核心依赖说明:express 是 Web 框架;cors 处理跨域;morgan 记录访问日志;helmet 加强安全头;nodemon 用于开发时自动重启。
三、入口文件与中间件
// app.js
const express = require('express');
const cors = require('cors');
const morgan = require('morgan');
const helmet = require('helmet');
const userRouter = require('./routes/users');
const app = express();
// 全局中间件
app.use(helmet());
app.use(cors());
app.use(express.json());
app.use(express.urlencoded({ extended: true }));
app.use(morgan('dev'));
// 路由挂载
app.use('/api/users', userRouter);
// 健康检查
app.get('/health', (req, res) => res.json({ status: 'ok' }));
// 404 处理
app.use((req, res) => {
res.status(404).json({ code: 404, message: '资源不存在' });
});
// 全局错误处理
app.use((err, req, res, next) => {
console.error(err);
res.status(err.status || 500).json({
code: err.status || 500,
message: err.message || '服务器内部错误'
});
});
module.exports = app;
四、路由设计
// routes/users.js
const express = require('express');
const router = express.Router();
const { list, detail, create, update, remove } = require('../controllers/users');
const { validateCreate, validateUpdate } = require('../validators/users');
router.get('/', list);
router.get('/:id', detail);
router.post('/', validateCreate, create);
router.put('/:id', validateUpdate, update);
router.delete('/:id', remove);
module.exports = router;
路由层只负责"分发",业务逻辑放到 controller,数据校验交给中间件,分层清晰。
五、Controller 与统一响应
// utils/response.js
exports.success = (res, data = null, message = 'ok') => {
res.json({ code: 0, message, data });
};
exports.fail = (res, code, message) => {
res.status(code).json({ code, message, data: null });
};
// controllers/users.js
const { success, fail } = require('../utils/response');
const userService = require('../services/userService');
exports.list = async (req, res, next) => {
try {
const { page = 1, size = 20, keyword } = req.query;
const result = await userService.list({ page, size, keyword });
success(res, result);
} catch (err) {
next(err);
}
};
exports.create = async (req, res, next) => {
try {
const user = await userService.create(req.body);
success(res, user, '创建成功');
} catch (err) {
next(err);
}
};
统一响应结构 { code, message, data },前端处理逻辑会简单很多。
六、参数校验:Joi
npm install joi
// validators/users.js
const Joi = require('joi');
exports.validateCreate = (req, res, next) => {
const schema = Joi.object({
name: Joi.string().min(2).max(20).required(),
email: Joi.string().email().required(),
age: Joi.number().integer().min(0).max(150)
});
const { error } = schema.validate(req.body);
if (error) return res.status(400).json({ code: 400, message: error.details[0].message });
next();
};
七、错误处理中间件
Express 的错误中间件必须接收 4 个参数 (err, req, res, next),否则不会被识别。建议自定义一个 HttpException 类,业务层抛出时携带状态码。
// utils/error.js
class HttpException extends Error {
constructor(status, message) {
super(message);
this.status = status;
}
}
module.exports = HttpException;
// 使用
const HttpException = require('../utils/error');
if (!user) throw new HttpException(404, '用户不存在');
八、连接数据库
npm install mysql2
// db/mysql.js
const mysql = require('mysql2/promise');
const pool = mysql.createPool({
host: process.env.DB_HOST,
user: process.env.DB_USER,
password: process.env.DB_PASS,
database: process.env.DB_NAME,
waitForConnections: true,
connectionLimit: 10
});
module.exports = pool;
使用连接池而非单连接,避免频繁建立/销毁连接的开销。生产环境务必通过环境变量管理敏感信息。
九、环境变量与启动脚本
# .env
PORT=3000
DB_HOST=localhost
DB_USER=root
DB_PASS=123456
DB_NAME=mydb
// package.json
"scripts": {
"dev": "nodemon server.js",
"start": "node server.js"
}
// server.js
require('dotenv').config();
const app = require('./app');
app.listen(process.env.PORT, () => {
console.log(`API running at http://localhost:${process.env.PORT}`);
});
十、API 测试
开发阶段用 Postman 或 Insomnia 测试,更推荐写自动化测试:
npm install -D supertest jest
// test/users.test.js
const request = require('supertest');
const app = require('../app');
test('GET /api/users 返回列表', async () => {
const res = await request(app).get('/api/users');
expect(res.status).toBe(200);
expect(res.body.code).toBe(0);
});
十一、小结
一套规范的 RESTful API 应该满足:URL 表达资源、动词表达动作、统一响应结构、参数严格校验、错误集中处理、敏感信息走环境变量、关键路径有测试覆盖。这套流程虽然简单,但能撑住绝大多数中小型项目。后续接入鉴权(JWT)、限流、文档自动生成(Swagger)都可以在此基础上叠加。