foka-ci/apps/server/README-RESTful-API.md

RESTful API 设计规范

概述

本项目采用 RESTful API 设计规范，提供统一、直观的 HTTP 接口设计。

API 设计原则

1. 资源命名规范

• 使用名词复数形式作为资源名称
• 示例：/api/projects、/api/users

2. HTTP 方法语义

• GET: 获取资源
• POST: 创建资源
• PUT: 更新整个资源
• PATCH: 部分更新资源
• DELETE: 删除资源

3. 状态码规范

• 200 OK: 成功获取或更新资源
• 201 Created: 成功创建资源
• 204 No Content: 成功删除资源
• 400 Bad Request: 请求参数错误
• 404 Not Found: 资源不存在
• 500 Internal Server Error: 服务器内部错误

项目 API 接口

项目资源 (Projects)

1. 获取项目列表

GET /api/projects

查询参数:

• page (可选): 页码，默认为 1
• limit (可选): 每页数量，默认为 10，最大 100
• name (可选): 项目名称搜索

响应格式:

{
  "code": 0,
  "message": "获取列表成功，共N条记录",
  "data": {
    "data": [
      {
        "id": 1,
        "name": "项目名称",
        "description": "项目描述",
        "repository": "https://github.com/user/repo",
        "valid": 1,
        "createdAt": "2024-01-01T00:00:00Z",
        "updatedAt": "2024-01-01T00:00:00Z",
        "createdBy": "system",
        "updatedBy": "system"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 100,
      "totalPages": 10
    }
  },
  "timestamp": 1700000000000
}

2. 获取单个项目

GET /api/projects/:id

路径参数:

• id: 项目ID（整数）

响应格式:

{
  "code": 0,
  "message": "获取数据成功",
  "data": {
    "id": 1,
    "name": "项目名称",
    "description": "项目描述",
    "repository": "https://github.com/user/repo",
    "valid": 1,
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z",
    "createdBy": "system",
    "updatedBy": "system"
  },
  "timestamp": 1700000000000
}

3. 创建项目

POST /api/projects

请求体:

{
  "name": "项目名称",
  "description": "项目描述（可选）",
  "repository": "https://github.com/user/repo"
}

验证规则:

• name: 必填，2-50个字符
• description: 可选，最多200个字符
• repository: 必填，有效的URL格式

响应格式:

{
  "code": 0,
  "message": "获取数据成功",
  "data": {
    "id": 1,
    "name": "项目名称",
    "description": "项目描述",
    "repository": "https://github.com/user/repo",
    "valid": 1,
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z",
    "createdBy": "system",
    "updatedBy": "system"
  },
  "timestamp": 1700000000000
}

4. 更新项目

PUT /api/projects/:id

路径参数:

• id: 项目ID（整数）

请求体:

{
  "name": "新项目名称（可选）",
  "description": "新项目描述（可选）",
  "repository": "https://github.com/user/newrepo（可选）"
}

验证规则:

• name: 可选，2-50个字符
• description: 可选，最多200个字符
• repository: 可选，有效的URL格式

响应格式:

{
  "code": 0,
  "message": "获取数据成功",
  "data": {
    "id": 1,
    "name": "新项目名称",
    "description": "新项目描述",
    "repository": "https://github.com/user/newrepo",
    "valid": 1,
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T12:00:00Z",
    "createdBy": "system",
    "updatedBy": "system"
  },
  "timestamp": 1700000000000
}

5. 删除项目

DELETE /api/projects/:id

路径参数:

• id: 项目ID（整数）

响应:

• HTTP 状态码: 204 No Content
• 响应体: 空

错误处理

验证错误 (400 Bad Request)

{
  "code": 1003,
  "message": "项目名称至少2个字符",
  "data": {
    "field": "name",
    "validationErrors": [
      {
        "field": "name",
        "message": "项目名称至少2个字符",
        "code": "too_small"
      }
    ]
  },
  "timestamp": 1700000000000
}

资源不存在 (404 Not Found)

{
  "code": 1002,
  "message": "项目不存在",
  "data": null,
  "timestamp": 1700000000000
}

最佳实践

1. 统一响应格式

所有 API 都使用统一的响应格式，包含 code、message、data、timestamp 字段。

2. 参数验证

使用 Zod 进行严格的参数验证，确保数据的完整性和安全性。

3. 错误处理

全局异常处理中间件统一处理各种错误，提供一致的错误响应格式。

4. 分页支持

列表接口支持分页功能，返回分页信息方便前端处理。

5. 软删除

删除操作采用软删除方式，将 valid 字段设置为 0，保留数据历史。