83 lines
2.0 KiB
Markdown
83 lines
2.0 KiB
Markdown
# 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注解是否完整
|
||
- 避免不必要的冗余，能写到工具函数的不要写在模块内 |