查看学习笔记
ARTICLE

Node.js搭建RESTful API完整流程

从路由设计到中间件、参数校验与错误处理,搭一套规范的API服务。

Node.js搭建RESTful API完整流程

Node.js搭建RESTful API完整流程

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)都可以在此基础上叠加。

返回列表