在现代Web开发中，RESTful API已经成为前后端分离架构的标准通信方式。一个设计良好的API不仅能够提升开发效率，还能为系统的可维护性和可扩展性打下坚实基础。本文将系统总结我在实际项目中积累的RESTful API设计经验，涵盖从规范制定到工程落地的完整流程。

一、RESTful API的核心设计原则

REST（Representational State Transfer）是一种软件架构风格，它强调资源的抽象和统一接口。设计RESTful API时，需要遵循以下核心原则：

1.1 资源导向的URL设计

RESTful API的URL应该代表资源，而非动作。资源应该是名词，使用复数形式。例如，获取用户列表的URL应该是/users而非/getUsers。

GET    /users          // 获取用户列表
GET    /users/:id      // 获取指定用户
POST   /users          // 创建用户
PUT    /users/:id      // 更新用户信息（全量）
PATCH  /users/:id      // 更新用户信息（部分）
DELETE /users/:id      // 删除用户

GET    /users/:id/posts    // 获取指定用户的文章
POST   /users/:id/posts    // 为指定用户创建文章

1.2 HTTP状态码的正确使用

HTTP状态码是API与客户端沟通的重要方式。正确使用状态码可以让API的语义更加清晰：

1.3 统一的响应格式

统一的响应格式可以降低客户端的处理复杂度。我的项目采用了以下响应结构：

// 成功响应
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "name": "张三",
    "email": "zhangsan@example.com"
  }
}

// 列表响应
{
  "code": 200,
  "message": "success",
  "data": {
    "list": [...],
    "pagination": {
      "page": 1,
      "pageSize": 10,
      "total": 100
    }
  }
}

// 错误响应
{
  "code": 400,
  "message": "请求参数错误",
  "errors": [
    { "field": "email", "message": "邮箱格式不正确" }
  ]
}

二、Node.js与Express的工程实践

Express作为Node.js最流行的Web框架，以其简洁灵活的特点被广泛使用。在实际项目中，我采用了分层架构来组织代码，确保各层职责清晰。

2.1 项目目录结构

src/
├── config/           # 配置文件
├── controllers/      # 控制器层（处理HTTP请求）
├── services/         # 服务层（业务逻辑）
├── repositories/     # 数据访问层
├── middlewares/      # 中间件
├── models/           # 数据模型
├── routes/           # 路由定义
├── utils/            # 工具函数
├── validators/       # 参数校验
└── app.js            # 应用入口

2.2 控制器层（Controller）

控制器层负责接收HTTP请求，调用服务层处理业务逻辑，然后返回响应。控制器不应该包含业务逻辑，只负责请求和响应的转换。

// controllers/userController.js
const userService = require('../services/userService');
const { successResponse, errorResponse } = require('../utils/response');

class UserController {
  async getUsers(req, res, next) {
    try {
      const { page = 1, pageSize = 10 } = req.query;
      const result = await userService.getUsers({ page, pageSize });
      return successResponse(res, result);
    } catch (error) {
      next(error);
    }
  }

  async getUserById(req, res, next) {
    try {
      const { id } = req.params;
      const user = await userService.getUserById(id);
      return successResponse(res, user);
    } catch (error) {
      next(error);
    }
  }

  async createUser(req, res, next) {
    try {
      const userData = req.body;
      const newUser = await userService.createUser(userData);
      return successResponse(res, newUser, 201);
    } catch (error) {
      next(error);
    }
  }
}

module.exports = new UserController();

2.3 服务层（Service）

服务层是业务逻辑的核心，负责处理数据的验证、转换和业务规则。服务层不应该直接操作数据库，而是通过仓储层来访问数据。

// services/userService.js
const userRepository = require('../repositories/userRepository');
const { hashPassword } = require('../utils/crypto');
const { ConflictError, NotFoundError } = require('../utils/errors');

class UserService {
  async getUsers({ page, pageSize }) {
    const skip = (page - 1) * pageSize;
    const [users, total] = await Promise.all([
      userRepository.findAll({ skip, limit: pageSize }),
      userRepository.count()
    ]);

    return {
      list: users,
      pagination: { page, pageSize, total }
    };
  }

  async createUser(userData) {
    const existingUser = await userRepository.findByEmail(userData.email);
    if (existingUser) {
      throw new ConflictError('该邮箱已被注册');
    }

    const hashedPassword = await hashPassword(userData.password);
    return userRepository.create({
      ...userData,
      password: hashedPassword
    });
  }
}

module.exports = new UserService();

三、JWT认证与授权机制

在Web应用中，身份认证和权限控制是必不可少的安全机制。JSON Web Token（JWT）是目前最常用的认证方案之一。

3.1 JWT认证流程

JWT认证的基本流程如下：用户登录成功后，服务器生成包含用户信息的JWT令牌返回给客户端；客户端在后续请求的Authorization头中携带该令牌；服务器验证令牌的有效性后处理请求。

// middlewares/auth.js
const jwt = require('jsonwebtoken');
const { UnauthorizedError } = require('../utils/errors');

const authMiddleware = (req, res, next) => {
  const authHeader = req.headers.authorization;
  
  if (!authHeader || !authHeader.startsWith('Bearer ')) {
    throw new UnauthorizedError('缺少认证令牌');
  }

  const token = authHeader.substring(7);
  
  try {
    const decoded = jwt.verify(token, process.env.JWT_SECRET);
    req.user = decoded;
    next();
  } catch (error) {
    throw new UnauthorizedError('无效的认证令牌');
  }
};

module.exports = authMiddleware;

3.2 权限控制

基于角色的访问控制（RBAC）是常见的权限管理方式。我在项目中实现了一个灵活的权限中间件：

// middlewares/permission.js
const checkPermission = (...allowedRoles) => {
  return (req, res, next) => {
    const { role } = req.user;
    
    if (!allowedRoles.includes(role)) {
      throw new ForbiddenError('无权访问该资源');
    }
    
    next();
  };
};

// 路由中使用
router.get('/admin/users', 
  authMiddleware, 
  checkPermission('admin', 'superadmin'),
  userController.getUsers
);

四、请求参数校验

严格的参数校验是保证API健壮性的重要环节。我在项目中使用Zod库来进行声明式的参数校验。

// validators/userValidator.js
const { z } = require('zod');

const createUserSchema = z.object({
  name: z.string().min(2, '用户名至少2个字符').max(50, '用户名最多50个字符'),
  email: z.string().email('邮箱格式不正确'),
  password: z.string().min(6, '密码至少6个字符').max(20, '密码最多20个字符'),
  age: z.number().int().min(0, '年龄不能为负数').optional(),
  role: z.enum(['user', 'admin']).default('user')
});

const updateUserSchema = createUserSchema.partial();

module.exports = { createUserSchema, updateUserSchema };

// middlewares/validate.js
const validate = (schema) => (req, res, next) => {
  try {
    schema.parse(req.body);
    next();
  } catch (error) {
    const messages = error.errors.map(e => ({
      field: e.path.join('.'),
      message: e.message
    }));
    res.status(400).json({
      code: 400,
      message: '请求参数错误',
      errors: messages
    });
  }
};

// 路由中使用
router.post('/users', validate(createUserSchema), userController.createUser);

五、错误处理与日志记录

统一的错误处理机制可以让API在面对异常时表现得更加优雅和可预测。

// middlewares/errorHandler.js
const errorHandler = (err, req, res, next) => {
  console.error('Error:', err);

  if (err.name === 'ValidationError') {
    return res.status(400).json({
      code: 400,
      message: '数据验证失败',
      errors: Object.values(err.errors).map(e => e.message)
    });
  }

  if (err.name === 'CastError') {
    return res.status(400).json({
      code: 400,
      message: '参数类型错误',
      detail: err.message
    });
  }

  if (err.name === 'JsonWebTokenError') {
    return res.status(401).json({
      code: 401,
      message: '无效的认证令牌'
    });
  }

  // 自定义错误
  if (err.statusCode) {
    return res.status(err.statusCode).json({
      code: err.statusCode,
      message: err.message
    });
  }

  // 未知错误
  res.status(500).json({
    code: 500,
    message: '服务器内部错误'
  });
};

module.exports = errorHandler;

六、API版本控制

随着业务发展，API不可避免地需要进行修改。合理的版本控制策略可以保证旧版本客户端的正常运行。

我的项目采用了URL路径版本控制的方式（如/api/v1/users），这种方式直观清晰，便于API文档的生成和维护。同时，我会在响应头中添加API版本信息，方便客户端进行版本检测。

// routes/index.js
const express = require('express');
const router = express.Router();

router.use('/api/v1', require('./v1'));
router.use('/api/v2', require('./v2'));

module.exports = router;

七、总结与反思

RESTful API的设计是一个需要持续迭代和完善的过程。在实际项目中，我总结了几点经验：

一个好的API设计不仅需要遵循规范，更需要结合实际业务场景进行灵活调整。希望本文的分享能为你的API设计实践提供一些参考和启发。