api_flow.md 18 KB
接口请求文档
1. 概述
本文档描述了 CRMEB 项目中 API 接口请求的流程、规范、参数设计和响应格式等，旨在统一 API 请求格式，提高 API 的一致性和可维护性。
2. 接口请求流程
2.1 基本流程
- 客户端发起请求: 客户端通过 HTTP/HTTPS 协议向服务器发送请求
- 请求到达服务器: 请求经过网络传输到达服务器
- 请求解析: 服务器解析请求，包括请求方法、路径、参数等
- 认证授权: 服务器对请求进行认证和授权
- 业务处理: 服务器执行相应的业务逻辑
- 生成响应: 服务器生成响应数据
- 返回响应: 服务器将响应返回给客户端
- 客户端处理响应: 客户端处理服务器返回的响应
2.2 详细流程
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ 客户端 │ │ 中间件 │ │ 控制器 │
│ 1. 发起请求 │────▶│ 2. 认证授权 │────▶│ 3. 业务处理 │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│
▼
┌─────────────────┐
│ 服务层 │
│ 4. 执行逻辑 │
└─────────────────┘
│
▼
┌─────────────────┐
│ 数据层 │
│ 5. 数据操作 │
└─────────────────┘
│
▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ 客户端 │ │ 中间件 │ │ 控制器 │
│ 8. 处理响应 │◀────│ 7. 响应处理 │◀────│ 6. 生成响应 │
└─────────────────┘ └─────────────────┘ └─────────────────┘
3. 请求方法
3.1 HTTP 方法
| 方法 | 描述 | 幂等性 | 安全性 |
|---|---|---|---|
| GET | 获取资源 | 是 | 是 |
| POST | 创建资源 | 否 | 否 |
| PUT | 更新资源 | 是 | 否 |
| DELETE | 删除资源 | 是 | 否 |
| PATCH | 部分更新资源 | 否 | 否 |
| OPTIONS | 获取资源的可用操作 | 是 | 是 |
| HEAD | 获取资源的元数据 | 是 | 是 |
3.2 方法使用规范
- GET: 用于获取资源，不应修改资源状态
- POST: 用于创建新资源
- PUT: 用于更新整个资源，应包含资源的完整表示
- DELETE: 用于删除资源
- PATCH: 用于部分更新资源，只包含需要更新的字段
- OPTIONS: 用于获取资源支持的 HTTP 方法
- HEAD: 用于获取资源的元数据，如 Content-Length、Last-Modified 等
4. 请求头
4.1 通用请求头
| 请求头 | 描述 | 示例 |
|---|---|---|
| Accept | 客户端可接受的响应内容类型 | application/json |
| Accept-Encoding | 客户端可接受的编码方式 | gzip, deflate |
| Content-Type | 请求体的内容类型 | application/json |
| Authorization | 认证信息 | Bearer {token} |
| User-Agent | 客户端标识 | Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36 |
| X-Requested-With | 请求类型 | XMLHttpRequest |
| X-Token | 认证令牌（自定义） | your_token_here |
4.2 自定义请求头
自定义请求头应以 X- 为前缀，如 X-Token、X-Request-ID 等。
5. 请求参数
5.1 参数位置
| 位置 | 适用场景 | 示例 |
|---|---|---|
| URL 路径 | 资源标识 | /api/v1/user/1 |
| 查询字符串 | 过滤、排序、分页 | /api/v1/user?page=1&limit=10&sort=create_time&order=desc |
| 请求体 | 复杂数据、创建/更新资源 | {"username": "test", "password": "123456"} |
| 请求头 | 认证信息、元数据 | Authorization: Bearer {token} |
| Cookie | 会话信息 | PHPSESSID=your_session_id |
5.2 参数命名规范
- 命名风格: 使用 camelCase 命名风格，如
userName - 语义化: 参数名应具有明确的语义，如
page、limit、sort - 简洁性: 参数名应简洁明了，避免过长
- 一致性: 相同类型的参数在不同接口中应保持一致
5.3 常用参数
| 参数名 | 类型 | 描述 | 示例 |
|---|---|---|---|
| page | int | 页码，默认 1 | page=1 |
| limit | int | 每页数量，默认 10 | limit=20 |
| sort | string | 排序字段 | sort=create_time |
| order | string | 排序方式，asc 或 desc | order=desc |
| keyword | string | 搜索关键词 | keyword=test |
| status | int | 状态过滤 | status=1 |
| start_time | string | 开始时间 | start_time=2024-01-01 |
| end_time | string | 结束时间 | end_time=2024-01-31 |
6. 请求体
6.1 内容类型
| 内容类型 | 描述 | 示例 |
|---|---|---|
| application/json | JSON 格式，最常用 | {"username": "test", "password": "123456"} |
| application/x-www-form-urlencoded | 表单格式 | username=test&password=123456 |
| multipart/form-data | 文件上传 | 包含文件和表单字段 |
| text/plain | 纯文本 | 简单的文本数据 |
| application/xml | XML 格式 | test123456 |
6.2 JSON 请求体规范
- 使用 camelCase 命名: 字段名使用 camelCase 命名风格
- 明确的数据类型: 使用适当的数据类型，如字符串、数字、布尔值、数组、对象
- 避免 null 值: 非必要字段不应包含 null 值
- 嵌套结构: 合理使用嵌套结构，避免过深的嵌套
- 数组格式: 数组元素类型应一致
示例：
{
"username": "test",
"password": "123456",
"nickname": "测试用户",
"age": 18,
"gender": 1,
"tags": ["tag1", "tag2"],
"address": {
"province": "北京",
"city": "北京",
"district": "朝阳区"
}
}
7. 响应格式
7.1 基本响应格式
所有 API 响应应使用统一的 JSON 格式，包含 status、msg 和可选的 data 字段。系统实际调用方式为 app('json')->success()。
7.1.1 调用示例
// 基本成功响应
return app('json')->success('操作成功', ['id' => 1, 'username' => 'test']);
// 只返回数据，不指定消息
return app('json')->success(['id' => 1, 'username' => 'test']);
// 使用系统内置成功码
return app('json')->success(100000); // 100000 是 "保存成功" 对应的系统内置成功码
7.1.2 响应格式
{
"status": 200,
"msg": "操作成功",
"data": {
"id": 1,
"username": "test",
"nickname": "测试用户"
}
}
7.2 分页响应格式
分页响应应包含 total、page、limit 和 list 字段，系统实际调用方式为 app('json')->success()。
7.2.1 调用示例
// 分页数据响应
$pageData = [
'total' => 100,
'page' => 1,
'limit' => 10,
'list' => [
['id' => 1, 'username' => 'test1', 'nickname' => '测试用户1'],
['id' => 2, 'username' => 'test2', 'nickname' => '测试用户2']
]
];
return app('json')->success('获取列表成功', $pageData);
7.2.2 响应格式
{
"status": 200,
"msg": "获取列表成功",
"data": {
"total": 100,
"page": 1,
"limit": 10,
"list": [
{
"id": 1,
"username": "test1",
"nickname": "测试用户1"
},
{
"id": 2,
"username": "test2",
"nickname": "测试用户2"
}
]
}
}
7.3 错误响应格式
系统使用统一的错误响应格式，所有错误响应通过 app('json')->fail() 方法返回。fail() 方法支持两种参数类型：
- 错误码（推荐）：系统内置的数字错误码，如
410025 - 错误消息：直接的字符串错误信息
7.3.1 统一响应格式
无论使用哪种参数类型，系统都会返回统一的 JSON 格式，包含 status、msg 和可选的 data 字段。当使用错误码时，响应中还会包含 code 字段。
{
"status": 400,
"msg": "账号或密码错误",
"code": 410025,
"data": null
}
7.3.2 调用示例
// 推荐：使用系统内置错误码
return app('json')->fail(410025);
// 不推荐：直接使用错误消息
return app('json')->fail('账号或密码错误');
// 使用错误码并传递额外数据
return app('json')->fail(410025, ['extra' => 'additional data']);
// 使用错误码并传递替换参数
return app('json')->fail(410025, [], ['field' => 'username']);
7.3.3 最佳实践
- 优先使用错误码：系统内置错误码经过统一规划，便于维护和国际化
- 避免直接使用字符串：直接使用字符串错误信息不利于国际化和统一管理
- 传递必要的额外数据：对于复杂错误，可以在
data字段中提供详细信息 - 使用替换参数：对于动态错误信息，使用替换参数提高灵活性
7.4 响应码规范
| 响应码范围 | 类型 | 描述 | 示例 |
|---|---|---|---|
| 200 | 成功 | 操作成功 | 200 |
| 1000-1999 | 系统级错误 | 系统核心错误 | 1001（参数错误） |
| 4000-4999 | 业务级错误 | 具体业务逻辑错误 | 410025（账号或密码错误） |
| 400 | 客户端错误 | 请求参数错误 | 400 |
| 401 | 认证错误 | 未认证或认证过期 | 401 |
| 403 | 权限错误 | 无权限访问 | 403 |
| 404 | 资源错误 | 资源不存在 | 404 |
| 500 | 服务器错误 | 服务器内部错误 | 500 |
8. 错误处理
8.1 错误响应设计
错误响应应遵循以下设计原则：
- 统一格式: 所有错误响应使用相同的 JSON 格式
- 明确的错误码: 使用唯一的错误码标识不同的错误类型
- 清晰的错误信息: 错误信息应简洁明了，便于理解
- 可选的详细信息: 对于复杂错误，可以在
data字段中提供详细信息 - HTTP 状态码匹配: 错误码应与 HTTP 状态码匹配
8.2 AI 自动提示系统内置错误码
CRMEB 系统集成了 AI 自动提示功能，当开发者在编写代码时使用 fail() 方法返回错误信息时，AI 会自动：
- 识别错误信息: 自动识别开发者输入的错误信息字符串
- 匹配内置错误码: 在系统内置错误码库中查找匹配的错误码
- 自动转换: 在运行时将错误信息自动转换为对应的系统内置错误码
- 提供建议: 对于未匹配到的错误信息，提供相似的错误码建议
- 实时提示: 在 IDE 中实时显示错误码建议
- 错误码文档: 在错误码文档 error_code.md，找到对应的错误码说明
8.2.1 功能示例
// 开发者输入
return $this->fail('登录失败');
// AI 自动提示并替换为
return $this->fail(410019); // 410019 是 "登录失败" 对应的系统内置错误码
8.2.2 工作原理
- 语言文件解析: 系统在运行时解析语言文件，构建错误码到错误信息的映射表
- 自动匹配: 当调用
fail()方法传入字符串错误信息时，系统自动在映射表中查找匹配的错误码 - 运行时转换: 如果找到匹配的错误码，系统会将错误信息替换为错误码，并在响应中包含
code字段 - 智能提示: 在 IDE 中，AI 会实时提示开发者使用正确的系统内置错误码
8.2.3 实际响应格式
当使用字符串错误信息时，系统会自动匹配并转换为错误码，最终响应格式为：
{
"status": 400,
"msg": "登录失败",
"code": 410019
}
当直接使用错误码时，响应格式为：
{
"status": 400,
"msg": "登录失败",
"code": 410019
}
8.3 错误处理最佳实践
- 使用系统内置错误码: 优先使用系统内置错误码，避免自定义错误信息
- 错误信息本地化: 使用
getLang()函数获取本地化的错误信息 - 详细的错误日志: 记录详细的错误日志，包括错误码、错误信息、请求参数等
- 友好的错误提示: 对客户端返回友好的错误信息，避免暴露系统内部细节
- 统一的错误处理: 使用统一的错误处理中间件处理所有错误
- 错误码文档化: 定期更新错误码文档，确保与实际代码一致
8.4 自定义错误码
对于系统内置错误码无法覆盖的业务场景，可以自定义错误码，但应遵循以下规范：
- 错误码范围: 使用系统未占用的错误码范围
- 命名规范: 错误码应具有明确的语义
- 文档化: 自定义错误码应在文档中明确说明
- 本地化: 自定义错误码应在语言文件中定义对应的错误信息
9. 接口开发流程
9.1 需求分析与设计
- 需求理解: 明确接口的业务需求和功能要求
- 资源设计: 确定接口涉及的资源和数据模型
- 接口设计: 设计接口的 URL、请求方法、参数和响应格式
- 权限设计: 确定接口的访问权限和认证方式
- 错误设计: 定义接口可能出现的错误情况和错误码
9.2 开发实现
- 创建路由: 在路由文件中定义接口路由
- 实现控制器: 创建控制器并实现接口逻辑
- 参数验证: 使用验证器对请求参数进行验证
- 业务逻辑: 实现接口的业务逻辑
- 错误处理: 使用
app('json')->fail()统一处理错误 - 响应返回: 使用
app('json')->success()统一返回响应
9.3 测试验证
- 单元测试: 编写单元测试验证接口功能
- 集成测试: 测试接口与其他模块的集成
- 接口测试: 使用 Postman 或其他工具测试接口
- 性能测试: 测试接口的性能和响应时间
- 安全测试: 测试接口的安全性
9.4 文档编写
- 接口文档: 编写接口的详细文档
- 错误码文档: 在
error_code.md中记录接口使用的错误码 - 变更记录: 记录接口的变更历史
9.5 上线发布
- 代码审查: 进行代码审查，确保代码质量
- 测试环境验证: 在测试环境验证接口功能
- 灰度发布: 灰度发布接口，观察运行情况
- 正式上线: 正式上线接口
9.6 监控维护
- 监控: 监控接口的运行状态和性能
- 日志: 记录接口的访问日志和错误日志
- 优化: 根据监控数据优化接口性能
- 维护: 定期维护和更新接口
10. 最佳实践
10.1 请求设计
- 使用 RESTful 风格: 遵循 RESTful API 设计规范
- 明确的资源命名: 使用明确的资源名称，如
/api/v1/user而不是/api/v1/getUser - 合理的 URL 层级: URL 层级不应过深，一般不超过 3 层
- 使用复数形式: 资源名称使用复数形式，如
/api/v1/users而不是/api/v1/user
10.2 参数设计
- 必填参数: 明确标识必填参数
- 默认值: 为可选参数提供合理的默认值
- 参数验证: 对所有参数进行验证
- 参数类型: 明确参数类型和格式
10.3 响应设计
- 统一格式: 使用统一的响应格式
- 明确的数据类型: 响应数据类型应明确
- 避免冗余数据: 只返回必要的数据
- 分页响应: 列表接口应支持分页
- 错误信息: 错误信息应清晰、准确
10.4 安全设计
- 认证授权: 使用 JWT 或 OAuth2 进行认证授权
- HTTPS: 使用 HTTPS 加密传输
- 参数验证: 严格验证所有输入参数
- 输出编码: 对输出数据进行编码，防止 XSS 攻击
- SQL 注入防护: 使用参数绑定，避免直接拼接 SQL
- CSRF 防护: 实现 CSRF Token 验证
11. 常见问题
11.1 跨域问题
- 问题: 浏览器同源策略导致跨域请求失败
- 解决方案: 实现 CORS（跨域资源共享），设置适当的响应头
10.2 认证失败
- 问题: 请求未携带认证信息或认证信息无效
- 解决方案: 检查请求头中的认证信息，确保令牌有效
10.3 参数错误
- 问题: 请求参数格式错误或缺少必填参数
- 解决方案: 检查请求参数，确保格式正确且包含所有必填参数
10.4 响应数据不符合预期
- 问题: 响应数据格式或内容不符合预期
- 解决方案: 检查 API 文档，确保请求格式正确，或联系 API 提供者
10.5 性能问题
- 问题: API 请求响应时间过长
- 解决方案: 优化 API 实现，使用缓存，减少数据库查询次数