# API 开发最佳实践总结

**基于场地预约管理系统开发实践**

## 📖 概述

本文档总结了场地预约管理系统的完整 API 开发实践，形成了一套标准化的 API 开发流程和规范，为后续 API 模块开发提供参考。

**实践基础**：

-   项目：校园管理系统 (hzdyjs_xg)
-   模块：场地预约管理系统
-   开发时间：2025-07-01
-   技术栈：Spring Boot 3.4.6 + MyBatis-Plus + Sa-Token

## 🎯 开发成果总览

### 完整交付物

| 类型       | 数量      | 文件/功能          | 质量标准     |
| ---------- | --------- | ------------------ | ------------ |
| 需求文档   | 2 个      | 业务需求+技术架构  | 完整详细     |
| 数据库脚本 | 3 个      | 表结构+字典+权限   | 规范标准     |
| 后端代码   | 18 个文件 | 完整 ruoyi 模块    | 符合架构规范 |
| API 接口   | 16 个     | 标准 CRUD+业务接口 | 功能完整     |
| API 文档   | 1 个      | 400+行详细文档     | 准确规范     |
| 测试脚本   | 1 个      | 450+行自动化测试   | 覆盖完整     |
| 变更记录   | 1 个      | 详细开发过程记录   | 追溯完整     |

### 开发时长统计

| 阶段       | 时间投入   | 主要工作             |
| ---------- | ---------- | -------------------- |
| 需求分析   | 0.5 天     | 需求整理+业务设计    |
| 数据库设计 | 0.5 天     | 表结构+权限+示例数据 |
| 后端开发   | 1.5 天     | 完整 ruoyi 模块开发  |
| API 文档   | 0.5 天     | 详细 API 文档编写    |
| 测试脚本   | 0.5 天     | 自动化测试脚本       |
| **总计**   | **3.5 天** | **完整 API 模块**    |

## 🚀 标准开发流程

### 阶段一：需求分析和文档创建（必须先行）

#### 1. 业务需求文档

```
docs/需求文档/[模块名]/
├── [模块名]系统需求说明.md     # 详细业务需求
└── README.md                  # 需求概览
```

**内容要求**：

-   项目概述和目标
-   详细业务流程分析
-   功能需求规格说明
-   数据模型设计
-   权限设计方案
-   验收标准定义

#### 2. 技术架构文档

```
docs/业务模块/[模块名]/
└── README.md                  # 技术架构说明
```

### 阶段二：数据库设计（代码开发前置条件）

#### 3. 数据库脚本创建

```
docs/设计文档/database/
├── XX-[模块名]-module.sql     # 数据表结构
├── XX-[模块名]-data.sql       # 字典数据
└── XX-[模块名]-menu.sql       # 菜单权限
```

**标准内容**：

-   **数据表**：2 个表（主实体+业务实体），包含标准基础字段
-   **字典数据**：2 个类型+6-9 条数据
-   **菜单权限**：12 个权限节点（目录+菜单+按钮）
-   **示例数据**：5-8 条测试数据

#### 4. 数据库执行验证

-   在测试环境执行 SQL 脚本
-   验证所有表结构、字典、权限、示例数据
-   确保数据库初始化完成

### 阶段三：后端模块开发

#### 5. ruoyi 模块标准结构

```
ruoyi-[模块名]/
├── pom.xml                          # 模块依赖配置
├── src/main/java/org/dromara/[模块名]/
│   ├── domain/                      # 实体类（3个类）
│   │   ├── [Entity].java           # 数据库实体
│   │   ├── bo/[EntityBo].java      # 业务对象
│   │   └── vo/[EntityVo].java      # 视图对象
│   ├── mapper/                      # 数据访问层（2个类）
│   │   └── [Entity]Mapper.java     # Mapper接口
│   ├── service/                     # 业务逻辑层（4个类）
│   │   ├── I[Entity]Service.java   # 服务接口
│   │   └── impl/[Entity]ServiceImpl.java # 服务实现
│   └── controller/                  # 控制器层（2个类）
│       └── [Entity]Controller.java # REST API控制器
└── src/main/resources/
    └── mapper/[Entity]Mapper.xml   # MyBatis映射文件（2个）
```

#### 6. 16 个标准 API 接口模式

**基础管理接口（6 个）**：

-   `GET /[module]/[entity]/list` - 分页查询列表
-   `GET /[module]/[entity]/{id}` - 查询详情
-   `POST /[module]/[entity]` - 新增
-   `PUT /[module]/[entity]` - 修改
-   `DELETE /[module]/[entity]/{ids}` - 删除
-   `GET /[module]/[entity]/available` - 获取可用选项

**业务功能接口（4 个）**：

-   `GET /[module]/[business]/my` - 查询我的数据
-   `GET /[module]/[business]/pending` - 查询待处理数据
-   `GET /[module]/[business]/conflict` - 业务规则检查
-   `POST /[module]/[business]/approve` - 审批操作

**辅助功能接口（6 个）**：

-   `POST /[module]/[business]/export` - 导出 Excel
-   `POST /[module]/[business]/import` - 导入 Excel
-   `GET /[module]/[business]/statistics` - 统计数据
-   `POST /[module]/[business]/batch` - 批量操作
-   `POST /[module]/[business]/{id}/enable` - 启用操作
-   `POST /[module]/[business]/{id}/disable` - 禁用操作

#### 7. 模块集成配置

-   `ruoyi-modules/pom.xml` - 添加子模块
-   `ruoyi-admin/pom.xml` - 添加依赖
-   `backend/pom.xml` - 版本管理配置

### 阶段四：API 文档编写（代码完成后立即执行）

#### 8. API 文档创建

```
docs/开发文档/API/
├── [模块名]管理API.md         # 完整API文档（400+行）
├── API文档总览.md             # 更新导航索引
└── API文档模板.md             # 标准模板
```

**标准文档结构**：

-   📖 概述和核心功能
-   🏢 主实体管理 API（6 个接口）
-   📅 业务实体管理 API（10 个接口）
-   📋 数据字典
-   🔐 权限配置
-   📏 业务规则
-   ❌ 错误码说明

### 阶段五：自动化测试脚本开发

#### 9. Python 测试脚本

```
test/
└── [模块名]API测试脚本.py      # 自动化测试脚本（450+行）
```

**标准脚本结构**：

-   强制 AES+RSA 双重加密登录
-   服务可用性检测
-   16 个 API 接口完整测试
-   业务规则验证测试
-   自动数据清理

### 阶段六：变更记录和验证

#### 10. 变更记录文档

```
docs/变更管理/
└── code-adjust-record-YYYY-MM-DD-{username}.md
```

#### 11. 完整功能验证

-   后端服务启动测试
-   API 接口功能测试
-   文档准确性验证
-   权限控制测试

## 🔧 技术实现要点

### 数据库设计规范

#### 强制性基础字段

```sql
`id` bigint(20) NOT NULL COMMENT '主键ID',
`tenant_id` varchar(20) NOT NULL DEFAULT '000000' COMMENT '租户编号',
`create_dept` bigint(20) DEFAULT NULL COMMENT '创建部门',
`create_by` bigint(20) DEFAULT NULL COMMENT '创建者',
`create_time` datetime DEFAULT NULL COMMENT '创建时间',
`update_by` bigint(20) DEFAULT NULL COMMENT '更新者',
`update_time` datetime DEFAULT NULL COMMENT '更新时间',
`deleted` tinyint(1) DEFAULT 0 COMMENT '删除标志（0代表存在 1代表删除）',
```

#### 业务字段设计原则

-   雪花 ID 作为主键
-   逻辑删除，禁止物理删除
-   多租户支持
-   完整的中文注释
-   合理的索引设计

### 后端代码规范

#### 实体类设计

```java
// 继承TenantEntity，包含完整注释
@TableName("table_name")
public class Entity extends TenantEntity {
    @TableId("id")
    private Long id;

    @TableField("field_name")
    private String fieldName;
}
```

#### 业务对象设计

```java
// 添加验证注解
public class EntityBo {
    @NotBlank(message = "字段不能为空", groups = {AddGroup.class, EditGroup.class})
    @Size(max = 100, message = "字段长度不能超过100个字符")
    private String fieldName;
}
```

#### 视图对象设计

```java
// 支持Excel导出
public class EntityVo {
    @ExcelProperty(value = "字段名称")
    private String fieldName;
}
```

#### 权限控制

```java
// 每个接口必须添加权限注解
@SaCheckPermission("module:entity:list")
@GetMapping("/list")
public TableDataInfo<EntityVo> list(EntityBo bo, PageQuery pageQuery) {
    // 接口实现
}
```

#### 响应格式规范

```java
// 分页接口直接返回TableDataInfo
@GetMapping("/list")
public TableDataInfo<EntityVo> list(...) {
    return entityService.queryPageList(bo, pageQuery);
}

// 非分页接口使用R类型
@GetMapping("/options")
public R<List<EntityVo>> options() {
    return R.ok(entityService.selectOptions());
}
```

### API 测试脚本规范

#### 强制加密登录

```python
# 强制依赖检查，缺少加密库直接退出
try:
    from Crypto.Cipher import AES
    from Crypto.Util.Padding import pad
    from Crypto.PublicKey import RSA
    from Crypto.Cipher import PKCS1_v1_5
    CRYPTO_AVAILABLE = True
except ImportError:
    print("❌ 缺少必需的加密库！")
    exit(1)
```

#### 标准测试流程

```python
def run_all_tests(self):
    # 1. 检测服务可用性
    if not self.get_server_info():
        return False

    # 2. 强制加密登录
    if not self.login():
        return False

    try:
        # 3. 执行各类测试
        self.test_entity_management()
        self.test_business_features()
        self.test_business_rules()
    finally:
        # 4. 清理测试数据
        self.cleanup_test_data()
```

## 📊 质量保证标准

### 开发完成标准

**一个完整的 API 模块开发必须包含**：

-   ✅ **完整的需求和技术文档**（2-3 个文档）
-   ✅ **数据库脚本和权限配置**（3 个 SQL 文件）
-   ✅ **完整的后端模块代码**（15-20 个 Java 文件）
-   ✅ **详细的 API 接口文档**（400+行）
-   ✅ **自动化测试脚本**（450+行）
-   ✅ **完整的变更记录日志**
-   ✅ **模块成功集成和功能验证**

### 文档质量标准

-   **完整性**：16 个标准接口的完整文档
-   **准确性**：所有参数和响应与实际代码一致
-   **详细性**：包含完整的业务规则和错误码说明
-   **规范性**：使用统一的文档模板和格式
-   **可测试性**：提供真实的请求响应示例

### 代码质量标准

-   **架构规范**：严格遵循 RuoYi-Vue-Plus 架构规范
-   **完整功能**：涵盖管理和业务的全流程
-   **权限控制**：实现接口权限和数据权限控制
-   **业务规则**：包含完整的业务验证逻辑
-   **可扩展性**：支持后续功能扩展和优化

## 💡 最佳实践经验

### 开发流程优化

1. **先文档后代码**：需求分析完成后再开始编码
2. **数据库优先**：表结构确定后再开发业务逻辑
3. **标准化接口**：16 个接口模式覆盖 90%的业务场景
4. **文档同步更新**：代码完成立即更新文档
5. **完整测试验证**：自动化测试确保质量
6. **规范化集成**：严格按照项目架构规范集成

### 常见问题和解决方案

#### 1. 版本配置问题

**问题**：新模块版本号不一致导致编译失败
**解决**：在根 pom.xml 的 dependencyManagement 中配置版本管理

#### 2. Excel 注解错误

**问题**：使用了错误的 Excel 注解包
**解决**：使用`cn.idev.excel.annotation.ExcelProperty`

#### 3. 登录认证问题

**问题**：API 测试脚本登录失败
**解决**：强制使用 AES+RSA 双重加密登录，确保加密库正确安装

#### 4. 文档不同步问题

**问题**：代码变更后文档未更新
**解决**：建立强制性文档同步更新规则，代码完成后立即更新文档

#### 5. MyBatis-Plus 实体字段映射问题 (2025-08-13 新增)

**问题**：SQL 错误 "Unknown column 'parent_name' in 'field list'"
**原因**：实体类中包含数据库表不存在的字段，MyBatis-Plus 自动生成 SQL 时包含了这些字段
**典型场景**：实体类中有用于显示的冗余字段（如 parentName），但数据库表中没有对应字段

**解决方案**：

```java
/**
 * 父部门名称（冗余字段，用于显示，不持久化到数据库）
 */
@TableField(exist = false)
private String parentName;
```

**关键要点**：
- 添加 `@TableField(exist = false)` 注解告诉 MyBatis-Plus 该字段不存在于数据库表中
- 导入正确的注解包：`import com.baomidou.mybatisplus.annotation.TableField;`
- 适用于所有用于显示但不持久化的冗余字段
- 避免在使用 `selectList()` 等 MyBatis-Plus 方法时出现字段不存在的错误

**错误示例**：
```
org.springframework.jdbc.BadSqlGrammarException: 
### Error querying database. Cause: java.sql.SQLSyntaxErrorException: Unknown column 'parent_name' in 'field list'
### SQL: SELECT dept_id, parent_id, ancestors, dept_name, order_num, leader, phone, email, status, del_flag, parent_name, dept_category, create_dept, create_by, create_time, update_by, update_time FROM sys_dept WHERE...
```

### 性能优化建议

1. **数据库查询优化**：合理使用索引，避免全表扫描
2. **分页查询优化**：使用 PageHelper 进行高效分页
3. **缓存策略**：对频繁查询的字典数据使用 Redis 缓存
4. **接口响应优化**：减少不必要的字段传输

## 📁 文件下载最佳实践 (2025-08-02 新增)

### 核心问题解决

基于OSS文件下载功能的修复经验，总结文件下载相关的最佳实践。

#### 1. 响应头设置规范

**🔴 关键点：二进制文件下载不要设置charset**

```java
// ❌ 错误方式 - 会导致下载失败
response.setContentType(MediaType.APPLICATION_OCTET_STREAM_VALUE + "; charset=UTF-8");

// ✅ 正确方式 - 纯二进制类型
response.setContentType(MediaType.APPLICATION_OCTET_STREAM_VALUE);

// ✅ 必需的缓存控制头
response.setHeader("Cache-Control", "no-cache, no-store, must-revalidate");
response.setHeader("Pragma", "no-cache");
response.setHeader("Expires", "0");
```

#### 2. Content-Length 正确设置

```java
// ❌ 可能失效的方法引用
storage.download(fileName, response.getOutputStream(), response::setContentLengthLong);

// ✅ 确保安全的设置方式
storage.download(fileName, response.getOutputStream(), contentLength -> {
    if (contentLength != null && contentLength > 0) {
        response.setContentLengthLong(contentLength);
    }
});
```

#### 3. 输出流处理

```java
try {
    // 文件下载逻辑
    storage.download(fileName, response.getOutputStream(), contentLengthConsumer);
    
    // 🔴 关键：必须手动刷新输出流
    response.getOutputStream().flush();
    
} catch (Exception e) {
    throw new ServiceException("文件下载失败: " + e.getMessage());
}
```

#### 4. 完整的文件下载模板

```java
@GetMapping("/download/{fileId}")
public void downloadFile(@PathVariable Long fileId, HttpServletResponse response) {
    try {
        // 1. 权限验证
        if (!hasDownloadPermission(fileId)) {
            throw new ServiceException("无权限下载该文件");
        }
        
        // 2. 获取文件信息
        FileVo fileInfo = fileService.getById(fileId);
        if (fileInfo == null) {
            throw new ServiceException("文件不存在");
        }
        
        // 3. 设置响应头
        FileUtils.setAttachmentResponseHeader(response, fileInfo.getOriginalName());
        response.setContentType(MediaType.APPLICATION_OCTET_STREAM_VALUE);
        response.setHeader("Cache-Control", "no-cache, no-store, must-revalidate");
        response.setHeader("Pragma", "no-cache");
        response.setHeader("Expires", "0");
        
        // 4. 执行下载
        OssClient storage = OssFactory.instance(fileInfo.getService());
        storage.download(fileInfo.getFileName(), response.getOutputStream(), contentLength -> {
            if (contentLength != null && contentLength > 0) {
                response.setContentLengthLong(contentLength);
            }
        });
        
        // 5. 刷新输出流
        response.getOutputStream().flush();
        
    } catch (Exception e) {
        log.error("文件下载失败: {}", e.getMessage(), e);
        throw new ServiceException("文件下载失败: " + e.getMessage());
    }
}
```

### 常见问题排查

#### 问题1：文件传输完成但客户端未收到
- **原因**：Content-Type包含charset或缺少flush()
- **解决**：移除charset，添加手动flush

#### 问题2：下载的文件损坏
- **原因**：Content-Length设置错误
- **解决**：使用lambda表达式确保Content-Length正确设置

#### 问题3：浏览器缓存导致下载异常
- **原因**：缺少缓存控制头
- **解决**：设置no-cache相关响应头

### 测试验证标准

1. **Postman测试**：能正确下载文件
2. **浏览器测试**：点击下载链接正常
3. **文件完整性**：下载文件与原文件MD5一致
4. **不同文件类型**：图片、文档、压缩包都能正常下载
5. **权限控制**：无权限用户被正确拒绝

## 🔄 持续改进

### 规范迭代

本最佳实践将根据后续项目开发经验持续优化：

1. **新技术集成**：随着技术栈升级调整开发规范
2. **流程优化**：根据开发效率反馈优化工作流程
3. **质量提升**：根据测试反馈完善质量标准
4. **工具改进**：开发更多自动化工具提升效率

### 应用推广

**适用场景**：

-   校园管理系统的其他业务模块
-   类似的管理信息系统
-   Spring Boot + MyBatis-Plus 架构的项目

**推广方式**：

-   作为新团队成员的培训材料
-   作为代码评审的质量标准
-   作为项目规划的参考模板

## 📚 参考文档

-   **后端开发规范**：`.cursor/cursorrules-backend.md`
-   **API 测试规范**：`.cursor/cursorrules-api-test.md`
-   **文档管理规范**：`.cursor/cursorrules-docs.md`
-   **实际案例参考**：
    -   `docs/开发文档/API/场地预约管理API.md`
    -   `test/场地预约API测试脚本.py`
    -   `docs/变更管理/code-adjust-record-2025-07-01-wuzilong.md`

---

**总结**：本最佳实践基于场地预约管理系统的成功开发经验，形成了一套完整的 API 开发标准流程，为后续 API 模块开发提供了可复制的标准模板和质量保证体系。

**维护人员**：开发团队  
**最后更新**：2025-08-02  
**文档版本**：v1.1 (新增文件下载最佳实践)

## 前端开发最佳实践

### 🎯 组件开发规范

#### ImagePreview图片预览组件
- **认证图片加载**: 通过axios获取blob数据，确保认证信息传递
- **内存管理**: 使用`onBeforeUnmount`清理blob URLs，防止内存泄漏
- **缓存优化**: 实现blob URL缓存机制，提升性能

**核心实现**:
```javascript
// 认证图片加载
const getImageBlobUrl = async (imageUrl: string): Promise<string> => {
  const response = await request({
    url: imageUrl,
    method: 'get',
    responseType: 'blob'
  });
  return URL.createObjectURL(response.data);
};

// 生命周期管理
onBeforeUnmount(() => {
  blobUrls.value.forEach(url => URL.revokeObjectURL(url));
});
```