后端 Java 接口 → 前端 TypeScript 接口生成
工作流程
- 解析输入：识别接口名称、地址、请求方式、请求参数（区分 Header/Body/Query/Path）、响应结构
- 过滤参数：排除 Header 注入参数（
LoginUser、userId、token等网关/拦截器注入字段） - 类型转换：按类型映射表将 Java 类型转为 TypeScript 类型
- 递归展开：嵌套 BO/VO/DTO 对象递归生成独立
interface - 组装输出：按固定格式输出接口概览 + TypeScript 代码块
- 标注疑问：信息不完整或有歧义时，在末尾以
> ⚠️ 注意：列出
类型映射
| Java 类型 | TypeScript 类型 | 备注 |
|---|---|---|
String / char / Character / UUID |
string |
|
int / Integer / short / Short / byte / Byte |
number |
|
long / Long |
number |
超大数值（如雪花 ID）用 string |
float / Float / double / Double / BigDecimal |
number |
高精度金额场景用 string |
boolean / Boolean |
boolean |
|
List<T> / Set<T> / Collection<T> / T[] |
T[] |
|
Map<String, V> / HashMap<String, V> |
Record<string, V> |
|
Date / LocalDateTime / LocalDate / Instant / ZonedDateTime |
string |
注释标注日期格式 |
byte[] / MultipartFile |
File |
文件上传场景 |
Object / JSONObject / JsonNode |
Record<string, unknown> |
|
Optional<T> |
映射为 T 并标记 ? |
|
void / Void |
— | 响应 result 为 null |
| 自定义 BO / VO / DTO | 生成对应 interface |
保留后端原始命名 |
| 枚举类 | 联合类型或 enum |
注释中列出所有枚举值 |
泛型包装处理
| 后端包装类型 | 展开方式 |
|---|---|
R<T> / Result<T> / Response<T> |
使用项目通用 ApiResponse<T>，不重复定义 |
PageResult<T> / IPage<T> / Page<T> |
见分页模板 |
分页响应模板：
interface XxxPageResultBO {
/** 总记录数 */
total: number;
/** 数据列表 */
result: XxxItemBO[];
}
参数处理
| 参数位置 | 处理方式 |
|---|---|
Header（LoginUser、userId、token 等） |
忽略，不出现在请求类型中 |
| Body | 生成 {接口名}RequestBody |
| Query | 生成 {接口名}RequestParams |
| Path | 在地址中以 {param} 标注，在请求类型中单独体现 |
| FormData / MultipartFile | 生成 {接口名}RequestBody，文件字段类型为 File |
响应处理：
- 外层统一使用 ApiResponse<T>（项目已有），不逐个生成
- result 实际类型单独定义为 interface
命名规范
| 类型 | 命名格式 | 示例 |
|---|---|---|
| 请求体 | {接口名}RequestBody |
ClaimCreditRequestBody |
| 查询参数 | {接口名}RequestParams |
ListVideoRequestParams |
| 响应结果 | {接口名}ResultBO |
ClaimCreditResultBO |
| 分页结果 | {接口名}PageResultBO |
ListVideoPageResultBO |
| 嵌套对象 | 保留后端原始命名 | ClaimDetailBO |
注释规范
- 每个字段使用 JSDoc
/** ... */，内容来源于后端文档参数说明 - 可选字段用
?标记，必填字段不加 - 枚举值完整列出：
/** 奖励类型: BASIC_RETURN / DOUBLE_RETURN */ - 日期格式标注：
/** 过期时间，格式: yyyy-MM-dd HH:mm:ss */
输出格式
输出为一个 .md 文件，包含所有接口的完整定义。多个接口之间用 --- 分隔。
文件命名规则： {飞书文档标题}-接口类型.md，文档标题从飞书文档中提取。
单个接口结构模板
**接口名称**
- **接口地址：** `/xxx/xxx`
- **请求方式：** `POST`
- **接口描述：** 一句话概括接口功能
- **请求参数：**
（TypeScript 代码块：请求相关类型）
- **响应结果：**
（TypeScript 代码块：响应相关类型）
规则说明
- 标题使用
**接口名称**加粗文本，不使用#标题 - 接口地址、请求方式、接口描述为列表项
- 请求参数 和 响应结果 各自独立一个 TypeScript 代码块
- 请求参数代码块包含：嵌套子对象（请求侧） + 请求类型
- 响应结果代码块包含：嵌套子对象（响应侧） + 响应结果类型
- 无请求参数时，省略「请求参数」及其代码块
- 每个
interface之间空一行 - 所有接口输出到同一个
.md文件中，文件名由用户指定或根据模块名自动生成
禁止包含：装饰性分隔注释、ApiResponse<T> 定义。
项目中已有的通用类型：
interface ApiResponse<T> {
code: number;
message: string;
result: T;
}
质量要求
- 不遗漏后端文档中的任何字段
- 字段名与后端完全一致，不擅自重命名
- 枚举值必须在注释中完整列出
- 日期/金额等格式化字段必须在注释中标注格式
- 接口描述总结为一句话，简明扼要
- 输出不得包含表格，所有信息使用列表或代码块
- 信息不完整或有歧义时，在末尾以
> ⚠️ 注意：列出疑问点
边界情况处理
| 场景 | 处理方式 |
|---|---|
嵌套泛型（如 List<Map<String, Object>>） |
展开为 Record<string, unknown>[] |
继承关系（如 extends BaseDTO） |
将父类字段合并到当前 interface |
| 同名但不同模块的类型 | 加模块前缀区分 |
| 字段可选性不明确 | 默认必填，并在疑问点中标注 |
| 响应为纯数组（非分页） | result 类型为 XxxItemBO[] |
| 无请求参数 | 不生成请求类型 |
| 多种 Content-Type | 按实际类型生成，multipart/form-data 中文件字段用 File |
完整示例
详见 examples.md
