CRMEB/.codebuddy/skills/php-api/references/api_create.md

接口开发流程文档

1. 概述

本文档描述了 CRMEB 项目中 API 接口的完整开发流程，包括需求分析、设计、开发、测试、文档编写、上线发布和监控维护等阶段。本流程旨在规范 API 开发过程，提高 API 的质量和可维护性。

2. 需求分析与设计

2.1 需求理解

1. 需求收集: 收集业务部门或产品经理提出的 API 需求
2. 需求分析: 分析需求的可行性、优先级和影响范围
3. 需求确认: 与需求方确认需求细节，确保理解一致
4. 风险评估: 评估需求实现过程中可能遇到的风险

2.2 资源设计

1. 数据模型设计: 设计 API 涉及的数据模型和数据库表结构
2. 资源定义: 定义 API 操作的资源和资源关系
3. 数据字段: 确定资源包含的字段和数据类型
4. 关联关系: 确定资源之间的关联关系

2.3 接口设计

1. URL 设计: 设计符合 RESTful 规范的 URL

   • 使用复数形式，如 /api/v1/users 而不是 /api/v1/user
   • 使用语义化名称，如 /api/v1/orders 而不是 /api/v1/getOrders
   • 合理的 URL 层级，一般不超过 3 层

2. 请求方法设计: 选择合适的 HTTP 请求方法

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

3. 参数设计: 设计请求参数

   • 路径参数: 用于标识资源，如 /api/v1/users/:id
   • 查询参数: 用于过滤、排序、分页，如 ?page=1&limit=10
   • 请求体参数: 用于创建或更新资源，使用 JSON 格式
   • 请求头参数: 用于认证、授权等

4. 响应设计: 设计统一的响应格式

   • 使用 app('json')->success() 返回成功响应
   • 使用 app('json')->fail() 返回错误响应
   • 统一的响应字段：status、msg、data，错误响应额外包含 code 字段
   • 分页响应包含 total、page、limit、list 字段

2.4 权限设计

1. 认证方式: 选择合适的认证方式

   • JWT 认证
   • OAuth2 认证
   • API Key 认证

2. 授权设计: 设计 API 的访问权限

   • 基于角色的访问控制 (RBAC)
   • 基于资源的访问控制 (RBAC)
   • 接口级别的权限控制

3. 访问控制: 实现 API 的访问控制

   • 使用中间件进行权限验证
   • 接口白名单机制
   • 接口速率限制

2.5 错误设计

1. 错误场景: 定义 API 可能出现的错误场景
2. 错误码: 从 error_code.md 文档中选择或申请合适的错误码
3. 错误信息: 设计清晰、准确的错误信息
4. 错误处理: 设计统一的错误处理机制

3. 开发实现

3.1 路由创建

1. 路由定义: 在路由文件中定义 API 路由
2. 路由分组: 使用路由分组组织相关 API
3. 中间件: 为路由添加必要的中间件
4. 命名路由: 为路由设置名称，便于生成 URL

示例代码:

// api/v1/route.php
use think\facade\Route;

// API 版本分组
Route::group('v1', function () {
    // 用户相关路由
    Route::group('users', function () {
        Route::get('', 'User/index'); // 获取用户列表
        Route::post('', 'User/save'); // 创建用户
        Route::get(':id', 'User/read'); // 获取用户详情
        Route::put(':id', 'User/update'); // 更新用户
        Route::delete(':id', 'User/delete'); // 删除用户
    })->middleware(['auth', 'permission']);
})->middleware(['cors', 'jwt']);

3.2 控制器实现

1. 创建控制器: 创建 API 控制器类
2. 继承基类: 继承项目的控制器基类
3. 实现方法: 实现 API 接口方法
4. 参数验证: 使用验证器验证请求参数
5. 业务逻辑: 实现 API 的业务逻辑
6. 响应返回: 使用统一的响应方法返回响应

示例代码:

// app/api/controller/v1/User.php
namespace app\api\controller\v1;

use app\BaseController;
use app\validate\User as UserValidate;
use app\services\UserServices;

class User extends BaseController
{
    protected $userServices;
    
    public function __construct(UserServices $userServices)
    {
        $this->userServices = $userServices;
    }
    
    /**
     * 获取用户列表
     */
    public function index()
    {
        $params = $this->request->param();
        $list = $this->userServices->getUserList($params);
        return app('json')->success('获取用户列表成功', $list);
    }
    
    /**
     * 创建用户
     */
    public function save()
    {
        $data = $this->request->post();
        // 参数验证
        $this->validate($data, UserValidate::class);
        // 业务逻辑
        $result = $this->userServices->createUser($data);
        // 返回响应
        return app('json')->success('创建用户成功', $result);
    }
    
    /**
     * 获取用户详情
     */
    public function read($id)
    {
        $user = $this->userServices->getUserById($id);
        if (!$user) {
            return app('json')->fail(400005); // 用户不存在
        }
        return app('json')->success('获取用户详情成功', $user);
    }
}

3.3 参数验证

1. 创建验证器: 创建 API 参数验证器
2. 定义规则: 定义参数验证规则
3. 错误信息: 定义验证错误信息，使用错误码
4. 验证调用: 在控制器中调用验证器

示例代码:

// app/validate/User.php
namespace app\validate;

use think\Validate;

class User extends Validate
{
    protected $rule = [
        'username' => 'require|length:3,20|unique:user',
        'password' => 'require|length:6,20',
        'email' => 'email|unique:user',
        'mobile' => 'mobile|unique:user',
        'status' => 'in:0,1',
    ];
    
    protected $message = [
        'username.require' => 400033, // 请填写管理员账号
        'username.length' => 400762, // 账号密码必须是在6到32位之间
        'username.unique' => 400001, // 用户名已存在
        'password.require' => 400020, // 密码必须填写
        'password.length' => 400762, // 账号密码必须是在6到32位之间
        'email.email' => 400003, // 邮箱已被注册
        'email.unique' => 400003, // 邮箱已被注册
        'mobile.mobile' => 400319, // 请输入正确的身份证
        'mobile.unique' => 400002, // 手机号已被注册
        'status.in' => 400751, // 状态必须是0-1之间的整数
    ];
}

3.4 业务逻辑实现

1. 服务层: 将业务逻辑封装到服务层
2. 模型层: 数据访问封装到模型层
3. 事务处理: 复杂业务使用事务处理
4. 错误处理: 统一处理业务逻辑错误

示例代码:

// app/services/UserServices.php
namespace app\services;

use app\model\User;
use crmeb\basic\BaseServices;

class UserServices extends BaseServices
{
    protected $userModel;
    
    public function __construct(User $userModel)
    {
        $this->userModel = $userModel;
    }
    
    /**
     * 获取用户列表
     */
    public function getUserList(array $params)
    {
        $page = $params['page'] ?? 1;
        $limit = $params['limit'] ?? 10;
        $keyword = $params['keyword'] ?? '';
        
        $query = $this->userModel->where('is_deleted', 0);
        
        if ($keyword) {
            $query->where('username|nickname|email|mobile', 'like', "%$keyword%");
        }
        
        $list = $query->page($page, $limit)->select();
        $total = $query->count();
        
        return [
            'total' => $total,
            'page' => $page,
            'limit' => $limit,
            'list' => $list
        ];
    }
    
    /**
     * 创建用户
     */
    public function createUser(array $data)
    {
        // 密码加密
        $data['password'] = password_hash($data['password'], PASSWORD_DEFAULT);
        $data['create_time'] = time();
        $data['update_time'] = time();
        
        return $this->userModel->save($data);
    }
}

3.5 错误处理

1. 使用错误码: 优先使用 error_code.md 中定义的错误码
2. 统一错误返回: 使用 app('json')->fail() 返回错误
3. 异常处理: 使用 try-catch 处理异常
4. 日志记录: 记录错误日志

示例代码:

// 正确使用方式
return app('json')->fail(410025); // 账号或密码错误

// 不推荐的使用方式
return app('json')->fail('账号或密码错误');

// 使用错误码并传递额外数据
return app('json')->fail(400086, [], ['field' => 'username']);

// 异常处理
try {
    // 业务逻辑
} catch (\Exception $e) {
    // 记录日志
    app('log')->error($e->getMessage());
    // 返回错误
    return app('json')->fail(500); // 系统错误
}

4. 测试验证

4.1 单元测试

1. 编写单元测试: 为 API 编写单元测试
2. 测试框架: 使用 PHPUnit 测试框架
3. 测试覆盖率: 提高测试覆盖率
4. CI/CD: 集成到 CI/CD 流程

示例代码:

// tests/api/UserTest.php
namespace tests\api;

use think\testing\TestCase;

class UserTest extends TestCase
{
    public function testIndex()
    {
        $response = $this->get('/api/v1/users');
        $response->assertStatus(200);
        $response->assertJsonStructure([
            'status',
            'msg',
            'data' => [
                'total',
                'page',
                'limit',
                'list' => [
                    '*' => [
                        'id',
                        'username',
                        'nickname',
                        'email',
                        'mobile',
                        'status'
                    ]
                ]
            ]
        ]);
    }
    
    public function testSave()
    {
        $data = [
            'username' => 'testuser',
            'password' => '123456',
            'email' => 'test@example.com',
            'mobile' => '13800138000',
            'status' => 1
        ];
        
        $response = $this->post('/api/v1/users', $data);
        $response->assertStatus(200);
        $response->assertJson(['status' => 200, 'msg' => '创建用户成功']);
    }
}

4.2 集成测试

1. 测试集成: 测试 API 与其他模块的集成
2. 数据库测试: 测试 API 对数据库的操作
3. 缓存测试: 测试 API 的缓存机制
4. 队列测试: 测试 API 与队列的集成

4.3 接口测试

1. 工具测试: 使用 Postman、Apifox 等工具测试 API
2. 测试用例: 编写完整的测试用例
3. 边界测试: 测试边界情况
4. 性能测试: 测试 API 的性能

4.4 安全测试

1. 认证测试: 测试 API 的认证机制
2. 授权测试: 测试 API 的授权机制
3. 注入测试: 测试 SQL 注入、XSS 等安全问题
4. 速率限制测试: 测试 API 的速率限制

5. 文档编写

5.1 接口文档

1. 编写接口文档: 编写详细的接口文档
2. 文档工具: 使用 Swagger、Apifox 等工具生成文档
3. 文档内容: 包括 URL、请求方法、参数、响应、错误码等
4. 示例: 提供请求和响应示例

5.2 错误码文档

1. 记录错误码: 在 error_code.md 文档中记录 API 使用的错误码
2. 错误码规范: 遵循项目的错误码规范
3. 错误码描述: 清晰描述错误码的含义和使用场景

5.3 变更记录

1. 记录变更: 记录 API 的变更历史
2. 变更类型: 包括新增、修改、删除等
3. 影响范围: 记录变更的影响范围
4. 版本管理: 管理 API 的版本

6. 上线发布

6.1 代码审查

1. 代码审查: 进行代码审查，确保代码质量
2. 审查标准: 遵循项目的代码规范
3. 安全审查: 审查代码的安全性
4. 性能审查: 审查代码的性能

6.2 测试环境验证

1. 部署测试: 在测试环境部署 API
2. 功能验证: 验证 API 的功能
3. 性能验证: 验证 API 的性能
4. 安全验证: 验证 API 的安全性

6.3 灰度发布

1. 灰度策略: 制定灰度发布策略
2. 灰度部署: 灰度部署 API
3. 监控观察: 监控 API 的运行情况
4. 逐步放量: 逐步增加灰度流量

6.4 正式上线

1. 上线准备: 准备上线所需的资源
2. 正式部署: 正式部署 API
3. 上线验证: 验证 API 的正常运行
4. 发布公告: 发布 API 上线公告

7. 监控维护

7.1 监控

1. 性能监控: 监控 API 的响应时间、QPS 等
2. 错误监控: 监控 API 的错误率、错误类型等
3. 可用性监控: 监控 API 的可用性
4. 日志监控: 监控 API 的访问日志和错误日志

7.2 日志

1. 访问日志: 记录 API 的访问日志
2. 错误日志: 记录 API 的错误日志
3. 慢查询日志: 记录 API 的慢查询日志
4. 日志分析: 定期分析日志

7.3 优化

1. 性能优化: 根据监控数据优化 API 性能
2. 安全优化: 加强 API 的安全性
3. 功能优化: 优化 API 的功能
4. 代码优化: 优化 API 的代码

7.4 维护

1. 定期维护: 定期维护 API
2. 版本更新: 更新 API 的版本
3. 漏洞修复: 修复 API 的漏洞
4. 文档更新: 更新 API 的文档

8. 最佳实践

8.1 设计最佳实践

1. 遵循 RESTful 规范: 使用 RESTful API 设计规范
2. 统一的命名规范: 使用统一的命名规范
3. 合理的 URL 设计: 设计简洁、语义化的 URL
4. 统一的响应格式: 使用统一的响应格式
5. 明确的错误码: 使用明确的错误码

8.2 开发最佳实践

1. 分层架构: 遵循分层架构设计
2. 依赖注入: 使用依赖注入
3. 参数验证: 严格验证请求参数
4. 事务处理: 合理使用事务
5. 缓存策略: 合理使用缓存

8.3 测试最佳实践

1. 自动化测试: 编写自动化测试
2. 测试覆盖率: 提高测试覆盖率
3. 边界测试: 测试边界情况
4. 性能测试: 测试 API 的性能
5. 安全测试: 测试 API 的安全性

8.4 上线最佳实践

1. 灰度发布: 使用灰度发布策略
2. 监控观察: 上线后密切监控
3. 回滚机制: 准备回滚机制
4. 发布公告: 及时发布公告

8.5 维护最佳实践

1. 监控预警: 设置监控预警
2. 定期巡检: 定期巡检 API
3. 日志分析: 定期分析日志
4. 性能优化: 持续优化性能
5. 文档更新: 及时更新文档

9. 常见问题

9.1 跨域问题

• 问题: 浏览器同源策略导致跨域请求失败
• 解决方案: 实现 CORS（跨域资源共享），设置适当的响应头

9.2 认证授权问题

• 问题: API 认证授权失败
• 解决方案: 检查认证信息，确保令牌有效，权限正确

9.3 参数验证问题

• 问题: 请求参数验证失败
• 解决方案: 检查请求参数，确保格式正确，包含所有必填参数

9.4 性能问题

• 问题: API 响应时间过长
• 解决方案: 优化 API 实现，使用缓存，减少数据库查询次数

9.5 安全问题

• 问题: API 存在安全漏洞
• 解决方案: 加强 API 的安全性，如使用 HTTPS、参数验证、防止 SQL 注入等

10. 参考资源

• RESTful API 设计指南
• HTTP 状态码
• API 设计最佳实践
• JSON API 规范
• OpenAPI 规范
• API 安全性最佳实践
• ThinkPHP 6 官方文档
• PHPUnit 官方文档
• Postman 官方文档