backend/api-development

后端 API 开发方法论

API 契约管理

契约来源

实现 API 前，必须阅读 architecture.md §5（API 设计），获取：

• API 规范（RESTful/GraphQL）
• 接口列表（方法、路径、描述、认证要求）
• 请求/响应格式约定
• 错误码规范

契约遵守原则

1. 严格实现：API 端点的方法、路径、参数必须与 architecture.md §5 一致
2. 响应格式：遵循统一的成功/错误响应结构
3. 偏差记录：如需偏离契约，必须在输出报告中标注原因
4. 类型导出：将请求/响应类型导出到共享文件，供前端引用

RESTful API 设计

资源命名规范

操作	HTTP 方法	路径	说明
列表	GET	/api/users	获取用户列表
详情	GET	/api/users/:id	获取单个用户
创建	POST	/api/users	创建新用户
更新	PUT/PATCH	/api/users/:id	更新用户
删除	DELETE	/api/users/:id	删除用户

统一响应格式

成功响应：

{
  "success": true,
  "data": { ... },
  "message": "Operation successful"
}

错误响应：

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": [
      { "field": "email", "message": "Invalid email format" }
    ]
  }
}

分页规范

请求参数：

GET /api/users?page=1&pageSize=20&sortBy=createdAt&order=desc

响应格式：

{
  "success": true,
  "data": {
    "items": [...],
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "total": 100,
      "totalPages": 5
    }
  }
}

请求验证

输入验证层级

1. 路由层：验证路径参数和查询参数
2. 中间件层：验证请求体格式和必填字段
3. Service 层：验证业务规则

验证示例

// 使用验证库（如 Zod、Joi、class-validator）
import { z } from 'zod';

const CreateUserSchema = z.object({
  name: z.string().min(1).max(100),
  email: z.string().email(),
  age: z.number().int().min(0).max(150).optional(),
});

// 在路由处理器中验证
app.post('/api/users', async (req, res) => {
  try {
    const validatedData = CreateUserSchema.parse(req.body);
    const user = await userService.create(validatedData);
    res.json({ success: true, data: user });
  } catch (error) {
    if (error instanceof z.ZodError) {
      res.status(400).json({
        success: false,
        error: {
          code: 'VALIDATION_ERROR',
          message: 'Invalid input data',
          details: error.errors,
        },
      });
    }
  }
});