kindergarten_java/docs/API 类型对比报告.md

API 类型对比报告

生成日期：2026-03-11

测试概述

1. API 生成测试 ✅

• orval 版本: v7.13.2
• 生成状态: 成功
• 输出文件: src/api/generated/api.ts + src/api/generated/model/*.ts
• 警告: 未找到全局安装的 prettier（不影响功能）

2. 后端 API 导出测试 ⚠️

• 后端地址: http://8.148.151.56:3002
• 测试结果: 无法连接（服务器可能关闭）
• 本地规范: api-spec.yml (408KB, 155 个接口)

3. TypeScript 编译检查 ⚠️

• 错误数量: 88 个
• 主要问题:
  • 未使用的变量 (TS6133): 约 50 个
  • 类型不匹配 (TS2322/TS2345): 约 20 个
  • 类型定义缺失 (TS2304/TS2724): 约 10 个
  • 其他类型错误：约 8 个

类型定义对比

ChildInfo (家长端 - 孩子信息)

字段	手写类型	生成类型	后端定义	状态
id	number	string	String	❌ 不一致
name	string	string	String	✅
gender	string	string	String	✅
birthDate	string	string	String	✅
relationship	string (必填)	string (可选)	String	⚠️ 可选性
class	{id, name, grade}	ClassInfo	ClassInfo	⚠️ 字段名
readingCount	number (必填)	number (可选)	Integer	⚠️ 可选性
lessonCount	number (必填)	number (可选)	Integer	⚠️ 可选性

修复建议:

// 修改 src/api/parent.ts
export interface ChildInfo {
  id: string;  // 改为 string
  name: string;
  gender?: string;
  birthDate?: string;
  relationship?: string;  // 改为可选
  classInfo?: {  // 改为 classInfo
    id: string;  // 改为 string
    name: string;
    grade: string;
  };
  readingCount?: number;  // 改为可选
  lessonCount?: number;  // 改为可选
}

Task (任务)

字段	手写类型	生成类型	后端定义	状态
id	number	number	Long	✅
title	string	string	String	✅
description	string	string	String	✅
taskType	`'READING'	'ACTIVITY'	'HOMEWORK'`	string
status	string	string	String	✅

Teacher (教师)

字段	手写类型	生成类型	后端定义	状态
id	number	number	Long	✅
name	string	string	String	✅
phone	string	string	String	✅
loginAccount	string	-	-	⚠️ 手写特有
status	string	string	String	✅
classIds	number[]	-	-	⚠️ 手写特有
classNames	string	-	-	⚠️ 手写特有

说明: 手写类型包含前端额外需要的字段（来自多个接口的组合）

主要问题总结

1. ID 类型不一致

• 后端部分 Entity 使用 String 类型作为 ID（如 ChildInfoResponse）
• 前端手写类型使用 number
• 影响: 可能导致类型校验失败或运行时错误

2. 字段命名不一致

• 后端使用 classInfo，前端使用 class
• 影响: 前端代码访问 child.class 会返回 undefined

3. 必填/可选不一致

• 后端所有字段都是可选的（Java 对象默认）
• 前端手写类型部分字段为必填
• 影响: 可能导致不必要的类型检查错误

4. 类型定义分散

• 同一个实体在不同接口有不同 Response 类型
• 例如 Teacher 有 TeacherInfoResponse, Teacher, PageResultTeacher 等
• 影响: 前端需要维护多个类型定义

修复优先级

高优先级 (影响功能)

1. ❌ ChildInfo.id 类型错误 (number → string)
2. ❌ ChildInfo.class 字段名错误 (class → classInfo)
3. ❌ Tenant.id 类型检查

中优先级 (类型安全)

1. ⚠️ 统一 ID 类型为 string 或 number
2. ⚠️ 添加枚举类型约束（如 TaskType, UserRole）
3. ⚠️ 更新可选字段标记

低优先级 (代码质量)

1. 📝 清理未使用的变量
2. 📝 修复 ESLint 警告
3. 📝 统一类型命名规范

测试结论

1. orval 生成工作正常，可以用于生成类型参考
2. 手写 API 类型需要更新以匹配后端实际返回
3. 建议建立类型同步流程：
   • 后端变更 → 更新 api-spec.yml → 重新生成 → 对比修复手写类型

下一步行动

1. 修复 src/api/parent.ts 中的 ChildInfo 类型
2. 检查其他 Response 类型的字段一致性
3. 添加运行时类型转换层（可选）