CRMEB/help/dev-docs/phpapi/开发规范说明.md

开发规范说明

🎯 基于已有规范的扩展

1. Service层命名和使用规范

// ✅ 正确示例
class UserServices extends BaseServices {
    public function getUserInfo(int $uid) {}
    public function updateUserStatus(int $uid, int $status) {}
}

// ❌ 避免在Controller中直接操作数据库
// 不要这样写：Db::name('user')->where('id', $uid)->update($data)

2. DAO层职责划分

// ✅ DAO只负责基础CRUD
class UserDao extends BaseDao {
    public function getById(int $id) {}
    public function updateById(int $id, array $data) {}
}

// Service调用DAO
class UserServices {
    public function complexBusiness() {
        $user = $this->dao->getById($id);
        // 业务逻辑处理
        $this->dao->updateById($id, $data);
    }
}

3. 异常处理标准

// 使用项目特定异常类
throw new ApiException('错误信息', 400);
throw new AdminException('管理端错误', 500);

// 统一返回格式
return $this->success($data);
return $this->fail('错误信息');

4. 参数验证位置

// 验证放在validate目录下对应文件
// adminapi/validate/user/UserValidata.php
class UserValidata extends Validate {
    protected $rule = [
        'nickname' => 'require|max:25',
        'phone' => 'require|mobile'
    ];
}

5. 注释标准补充

/**
 * 获取用户信息（包含扩展信息）
 * @param int $uid 用户ID
 * @param array $with 关联查询 ['order', 'address']
 * @return array
 * @throws ApiException
 */
public function getUserDetail(int $uid, array $with = []) {
    // 业务逻辑
}

🔧 工具类使用规范

• 使用 crmeb\utils\ 下的工具类
• 配置获取使用 SystemConfigService
• 缓存操作使用 CacheService
• 文件上传使用 UploadService

📝 代码提交规范

1. 提交前运行测试
2. 提交信息格式：[类型] 描述
   • [feat] 新增用户积分功能
   • [fix] 修复订单状态更新问题
   • [docs] 更新API文档
   • [style] 调整代码格式
3. 避免大块提交，每个提交专注于一个功能或修复

🚧 分支管理

• master - 生产环境代码
• develop - 开发分支
• feature/xxx - 功能开发分支
• hotfix/xxx - 紧急修复分支

🧪 测试规范

1. 单元测试覆盖核心业务逻辑
2. 集成测试覆盖API接口
3. 测试数据使用工厂模式生成
4. 测试用例命名：testMethodNameWhenConditionThenResult

---

提示：该文档由AI生成，仅供参考。