# 实现API

## 规则（Rules）

# 实现API接口 - 规范

## 1. 目录结构规范
```
./project/{项目名}/server/
├── routes/              ← 路由定义（只做URL映射）
├── controllers/         ← 控制器（业务逻辑）
├── models/              ← 数据模型（数据库操作）
├── validators/          ← 参数校验
├── middleware/          ← 中间件
└── utils/               ← 工具函数
```

## 2. 分层职责规范
- **路由（routes）**：只做URL映射和方法分发，不写业务逻辑
- **控制器（controllers）**：处理请求、调用服务、返回响应
- **模型（models）**：数据访问和数据库操作
- **校验器（validators）**：请求参数校验

## 3. 代码规范
- 函数命名使用小驼峰（camelCase）
- 变量和参数命名使用小写蛇形（snake_case）
- 常量命名使用全大写蛇形（SCREAMING_SNAKE_CASE）
- 缩进统一使用2个空格
- 注释使用JSDoc格式

## 4. 参数校验规范
- 所有用户输入必须经过校验
- 校验内容包括：必填字段、类型、格式、取值范围

## 方法（Methods）

# 实现API接口 - 方法

## 流程概览
```
读取API文档 → 编写路由 → 编写校验器 → 编写模型 → 编写控制器 → 注册路由 → 验证完整性
```

## 步骤1：读取API设计文档
读取API设计文档，提取每个接口的请求方法、路由路径、请求参数、响应格式、业务逻辑描述。

## 步骤2：编写路由定义
对每个资源模块编写路由文件，路由只做URL映射，不写业务逻辑。

## 步骤3：编写参数校验器
对每个接口的请求参数编写校验规则，检查必填字段、类型、格式。

## 步骤4：编写数据模型
对每个数据实体编写模型文件，封装CRUD数据库操作。

## 步骤5：编写控制器
实现具体业务逻辑，调用模型层获取数据，返回统一格式响应。

## 步骤6：注册路由到应用入口
确保入口文件已注册新编写的路由文件。

## 步骤7：验证接口完整性
检查每个接口是否都有对应的路由、校验器、控制器和模型。

## 技巧（Tips）

# 实现API接口 - 技巧

## 1. 统一响应格式
封装统一的成功/失败响应函数，避免每个控制器重复编写。

## 2. 错误处理
在控制器层使用 try-catch 捕获异常，返回统一的错误响应。

## 3. 数据验证
在校验器层做数据清洗（如去除首尾空格、格式标准化），减少控制器中的重复逻辑。

## 4. 事务处理
涉及多个数据表更新的操作，使用数据库事务保证数据一致性。