makemd/docs/RULES/api.md

API规则

入口: _index.md

---

1. 路由规范

1.1 路由格式

/api/{版本}/{模块}/{资源}/{动作}

示例:
/api/v1/products                    # 商品列表
/api/v1/products/:id                # 商品详情
/api/v1/products/:id/publish        # 商品刊登
/api/v1/orders                      # 订单列表
/api/v1/orders/:id/fulfill          # 订单履约

1.2 HTTP方法映射

方法	用途	示例
GET	查询	GET /api/v1/products
POST	创建	POST /api/v1/products
PUT	全量更新	PUT /api/v1/products/:id
PATCH	部分更新	PATCH /api/v1/products/:id
DELETE	删除	DELETE /api/v1/products/:id

---

2. 权限校验

2.1 中间件使用

// ✅ 正确：路由层使用 authorize() 中间件
router.get('/api/v1/products', authorize('product:read'), ProductController.list);
router.post('/api/v1/products', authorize('product:create'), ProductController.create);
router.put('/api/v1/products/:id', authorize('product:update'), ProductController.update);

// ❌ 错误：Controller 中硬编码角色
async create(ctx: Context) {
  if (ctx.state.user.role === 'ADMIN') { // 禁止
    // ...
  }
}

2.2 权限格式

{模块}:{动作}

示例:
product:read      # 查看商品
product:create    # 创建商品
product:update    # 更新商品
product:delete    # 删除商品
order:fulfill     # 订单履约
finance:approve   # 财务审批

2.3 数据隔离

非 ADMIN 用户查询必须根据 parentId 层级过滤：

// ✅ 正确：Service层处理数据隔离
async listProducts(ctx: Context) {
  const { tenantId, role, parentId } = ctx.state.user;
  
  const query = db('cf_product').where('tenant_id', tenantId);
  
  if (role !== 'ADMIN') {
    query.where('parent_id', parentId);
  }
  
  return query;
}

---

3. 响应格式

3.1 成功响应

// 单条数据
{
  "success": true,
  "data": { ... }
}

// 列表数据
{
  "success": true,
  "data": [...],
  "pagination": {
    "total": 100,
    "page": 1,
    "pageSize": 20
  }
}

3.2 错误响应

{
  "success": false,
  "error": {
    "code": "PRODUCT_NOT_FOUND",
    "message": "商品不存在",
    "details": {}
  }
}

3.3 错误码规范

前缀	类别	示例
VAL_	参数校验	VAL_INVALID_PARAM
AUTH_	认证授权	AUTH_UNAUTHORIZED
BIZ_	业务逻辑	BIZ_PRODUCT_NOT_FOUND
SYS_	系统错误	SYS_DATABASE_ERROR

---

4. 请求参数

4.1 分页参数

// 请求
GET /api/v1/products?page=1&pageSize=20

// 响应
{
  "data": [...],
  "pagination": {
    "total": 100,
    "page": 1,
    "pageSize": 20,
    "totalPages": 5
  }
}

4.2 排序参数

// 请求
GET /api/v1/products?sortBy=created_at&sortOrder=desc

// 默认排序
sortBy: 'created_at'
sortOrder: 'desc'

4.3 过滤参数

// 请求
GET /api/v1/products?platform=SHOPIFY&status=ACTIVE

// 多值过滤
GET /api/v1/products?platform=SHOPIFY,AMAZON

---

5. 追踪字段

所有API请求必须携带五元组：

// 请求头
{
  'X-Tenant-Id': 'xxx',
  'X-Shop-Id': 'xxx',
  'X-Task-Id': 'xxx',      // 可选
  'X-Trace-Id': 'xxx',
  'X-Business-Type': 'TOC'
}

// 或请求体
{
  "tenantId": "xxx",
  "shopId": "xxx",
  "taskId": "xxx",
  "traceId": "xxx",
  "businessType": "TOC"
}

---

6. 速率限制

端点类型	限制	窗口
查询接口	100次	1分钟
写入接口	30次	1分钟
批量接口	10次	1分钟

---

最后更新: 2026-03-22