一、接口规范

1. 基础规范

• HTTP方法限定：
  • GET：仅用于数据查询（如获取列表、详情）
  • POST：用于写操作（如创建、更新、删除）
• URL设计：
  • 全小写+下划线，示例（api/模块/业务/操作）：
    • GET /api/user/user/profile（用户详情）
    • POST /api/order/invoce/create（创建订单发票）

3. 安全要求

• 输入验证：
  • 数据：使用过滤字段和默认值，示例：

    $this->request->only([
            'is_enabled/d' => 1,
            'page/d' => 1,
            'size/d' => 15,
            'sort_field' => 'id',
            'sort_order' => 'desc',
        ], 'get');
        
     或
     input('flow_type/d', 1);
    

---

二、传参规格

1. GET参数

• 场景：过滤、分页、排序等。
• 规范：
  • 参数命名清晰，如?page=2&page_size=10
  • 避免敏感信息（如密码）出现在URL中。
  • 示例：

    // 分页查询用户列表
    GET /api/v1/users?page=2&status=active&order_by=created_at&sort=desc
    

2. POST参数

• 场景：创建资源、复杂操作。
• 数据格式：
  • JSON（json body）：Content-Type: application/json

    {
      "data": {
        "name": "name",
        "avatar": "http://xxx.png"
      }
    }
    

  • FormData：Content-Type: multipart/form-data（文件上传）
• 校验规则：

  • 必填字段验证（如empty($data['name'])）。

  • 如果body数据比较大使用Validate校验：

    protected $rule = [
        'log_info' => 'require|max:100',
    ];
    
    protected $message = [
        'log_info.require' => '管理员日志名称不能为空',
        'log_info.max' => '管理员日志名称最多100个字符',
    ];
    

---

三、Service层规范

1. 核心职责

• 业务逻辑：处理复杂计算、流程控制。
• 数据整合：调用多个Model组合数据。
• 事务管理：保证数据库操作的原子性。

2. 设计原则

• 单一职责：每个Service方法只做一件事。
• 依赖隔离：
  • 禁止在Service中直接操作GET或POST或request参数如获得用户id或指定request参数。
  • 数据通过参数传递，例如：

    // 正确做法：通过参数传递
    public function updateUser(int $userId, array $data) { ... }
    
    // 错误做法：直接读取全局变量
    public function updateUser() {
        $data = request()->userId; // 耦合请求层
    }
    

---

四、附录：分层架构示意图

HTTP请求
   │
   ▼
 控制器（Controller）
   │ 接收参数 → 基础校验 → 调用Service
   ▼
 服务层（Service）
   │ 处理业务逻辑 → 操作多个Model → 管理事务
   ▼
 模型层（Model）
   │ 数据库CRUD → 数据关系映射

---

关键总结

1. 接口设计：URL清晰、数据格式统一、命名可读清晰、方法合理。
2. 参数安全：严格过滤输入，使用预处理防御注入。
3. Service核心：封装业务逻辑，通过依赖注入解耦。
4. 事务控制：确保关键操作原子性（如订单创建+扣库存）。
5. 兼容JAVA和前端 同时须知JAVA要求和前端要求做到兼容JAVA和前端