# API 开发规范

## 核心要点

一定要阅读customer模块的实现，看看其他模块的实，明白编码细节，现然后再进行开发。

### 1. 分层架构
```
internal/
├── models/          # 数据模型：结构体定义、验证规则
├── service/         # 业务逻辑：核心业务规则实现
├── repository/      # 数据访问：数据库、缓存操作
└── api/handlers/    # HTTP处理：请求处理、响应格式化
```

**职责边界**：
- Models：数据结构、输入验证、响应格式
- Service：业务规则、数据处理、跨模块协调
- Repository：数据持久化、查询优化、事务管理
- Handler：HTTP协议、参数绑定、错误响应

### 2. 多语言支持

**枚举字段扩展**：为所有枚举类型添加`*_display`字段
```json
{
  "status": "active",
  "status_display": "激活",
  "customer_type": "enterprise", 
  "customer_type_display": "企业客户"
}
```

**语言检测优先级**：
1. URL参数：`?lang=en-US`
2. HTTP Header：`Accept-Language`
3. 系统默认：配置文件指定

### 3. 错误处理

**错误码规范**：六位数字
- 前2位：模块代码（10=认证，20=客户，30=授权，90=系统）
- 后4位：连续错误号

**统一响应格式**：
```json
{
  "code": 0,
  "message": "success",
  "data": {...}
}
```

### 4. RESTful设计

**路由规范**：
- 使用名词表示资源
- HTTP方法体现操作
- 版本控制：`/api/v1/`

**HTTP状态码**：
- 200：成功（包括业务逻辑失败）
- 400：请求格式错误
- 401：身份认证失败
- 403：权限不足
- 500：服务器内部错误

### 5. 开发流程

1. 定义模型结构（含多语言字段）
2. 声明服务接口
3. 实现业务逻辑（添加i18n处理）
4. 编写HTTP处理器
5. 注册路由
6. 完善Swagger文档

### 6. 质量检查

- 分层职责是否清晰
- 多语言字段是否完整
- 错误处理是否统一
- Swagger注解是否完整
- 避免不必要的冗余，能写到工具函数的不要写在模块内