---
globs: ["**/controller/**", "**/api/**", "**/*Controller.java", "**/*Api.java", "**/interfaces/**"]
---

# API 接口设计规范

## 接口文档管理
- 对自身系统的接口文档负责，接口变更时及时维护并备注变更时间
- 参数的必填/非必填、类型、简介必须准确完整
- 服务间调用接口在模块或接口处添加 **S** 标识
- Web 前端调用接口添加 **U** 标识
- 对外服务接口上下文以 `[-api]` 结尾，如 `zqyl-crcl-api`

## 接口地址规则
- 地址体现结构：`/服务/模块/功能`，如 `/zqyl-loan-application-api/finance/financeManageList`
- 接口路径使用驼峰命名
- URL 路径禁止使用大写字母，单词分隔使用下划线
- 路径禁止携带内容类型后缀（`.json`、`.xml`）
- 功能命名后缀约定：
  - 列表：`*List`
  - 存储：`*Save`
  - 新增：`*Add`
  - 详情：`*Detail`
  - 导出：`*Export`
  - 删除：`*Delete`
  - 下载：`*Download`
  - 上传：`*Upload`

## 请求方式规范
- 查询类接口使用 **GET** 请求，以 Query String Parameter 形式传参
- 新增/保存类接口使用 **POST** 请求，以 JSON 请求体传参
- 批量传参操作一律使用 **POST** 请求，不论读写
- PUT 用于更新资源，DELETE 用于删除资源
- body 传参时必须设置 `Content-Type: application/json`

## 请求示例
```java
// GET 查询 - Controller 统一返回 ResultData（禁止 ResponseInfo，避免双重包装）
@GetMapping(value = "queryDetail")
public ResultData<SomeVO> queryDetail(@RequestParam("id") String id) {
    return someApplication.queryDetail(id);
}

// POST 写操作
@PostMapping("/saveSome")
public ResultData<Void> saveSome(@RequestBody SomeSaveDTO req) {
    return someApplication.saveSome(req);
}
```
> 注：`ResponseInfo`/`ResponseInfoUtil` 仅用于 Feign 客户端反序列化外部服务响应，**不用于 Controller 返回**。

## 数据格式规范
- 超大整数（如 id）服务端使用 String 返回，使用 `@JSONField(serializeUsing = ToStringSerializer.class)` 注解
- 日期字段统一使用时间戳格式返回，展示由前端处理
- 列表接口返回为空时，返回空数组 `[]` 或空集合 `{}`
- 创建类接口完成后直接返回该数据 `id`

## 通用报文结构

### Header
- `Authorization`: 客户端 token（String）
- `Xsrf-Token`: 防 XSRF 攻击 token（String）

### 请求通用参数（列表适用）
- `page`: 分页页数（Number）
- `pageRow`: 分页显示条数（Number）

### 响应通用结构
- `status`: 状态码（String）
- `msg`: 用户可见消息（String）
- `total`: 记录总数（Number，列表适用）
- `data`: 具体数据（Object/List/String）

### 属性类型约定
- 有限长度数值：`int`
- 枚举类型：`Integer`
- 金额：`BigDecimal`
- 日期：时间戳
- 超 19 位数值：`String`

## 状态码规范
| 码段 | 含义 | 处理方式 |
|------|------|---------|
| M020x | 操作成功 | 执行正确逻辑 |
| M030x | 用户数据提交有误 | 阻止操作，前端提示 |
| M040x | 用户状态变更 | 阻止操作，退出登录 |
| M050x | 服务端异常 | 阻止操作，后端排查 |

常用状态码：`M0200`（成功）、`M0201`（成功但不执行标准逻辑）、`M0401`（登录失效）、`M0500`（服务端异常）

## 响应体错误信息
- 服务端错误必须包含：HTTP 状态码、errorCode、errorMessage、用户提示信息
- errorMessage 简要描述后端错误原因，禁止包含敏感数据
- 用户提示信息要简短清晰、友好引导

## 版本控制
- 接口路径中不加版本号，版本控制在 HTTP 头信息中体现
- App 端如需版本控制，可在 URL 包含版本（如 `/api/v1/`）

## 常见错误模式
- ❌ 返回 `Long` 类型 id → ✅ 使用 `String` 或 `@JSONField(serializeUsing = ToStringSerializer.class)`
- ❌ 返回 null 的列表 → ✅ 返回空数组 `[]`
- ❌ GET 请求传递批量参数 → ✅ 使用 POST + JSON 请求体
- ❌ `ERROR_CODE` / `error-message` → ✅ `errorCode` / `errorMessage`（lowerCamelCase）