RESTful API 设计最佳实践

发布时间：2025-05-30 | 分类：后端开发

RESTful 规范核心原则

资源导向：使用名词而非动词，如 /users、/orders
HTTP 方法：GET 查询、POST 创建、PUT 更新、DELETE 删除
状态码：正确使用 200、201、400、401、404、500 等状态码
无状态：每个请求包含所有必要信息

API 路由设计

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

请求参数规范

查询参数（Query String）

分页：?page=1&limit=20
排序：?sort=createdAt&order=desc
筛选：?status=active&type=vip
搜索：?keyword=张三

路径参数

资源ID：/users/:id
子资源：/users/:id/orders
级联：/departments/:deptId/users/:userId

请求体（JSON）

{
  "username": "zhangsan",
  "email": "zhangsan@example.com",
  "password": "********",
  "role": "admin"
}

响应格式规范

// 成功响应
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1,
    "username": "zhangsan"
  },
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100
  }
}

// 错误响应
{
  "code": 4001,
  "message": "用户名已存在",
  "detail": {}
}

Koa.js 实现示例

const Router = require('koa-router');
const router = new Router({ prefix: '/api/users' });

// 获取用户列表
router.get('/', async (ctx) => {
  const { page = 1, limit = 20 } = ctx.query;
  const users = await User.find()
    .skip((page - 1) * limit)
    .limit(Number(limit));

  ctx.body = {
    code: 0,
    data: users,
    pagination: { page, limit, total: await User.count() }
  };
});

// 创建用户
router.post('/', async (ctx) => {
  const user = await User.create(ctx.request.body);
  ctx.status = 201;
  ctx.body = { code: 0, data: user };
});