obsidian-vault/projects/frontend/dto-guidelines.md

类型定义规范

前端请求参数、响应数据类型以及页面数据模型的定义规范。

---

命名原则

• 类型名要体现用途，例如 LoginParams、OrderListItem、UserDetailResponse
• 优先使用业务语义命名，不用后端传输层术语硬套前端场景
• 名称要与实际使用场景一致，不要出现“通用类型”却只服务单一页面的情况
• 页面私有类型优先就近定义在页面目录；全局复用类型再抽到公共位置

---

字段设计原则

• 只保留当前页面、组件、Hook 真实需要的字段
• 字段语义必须单一明确，不要一个字段承担多种含义
• 嵌套对象只在确实提升可读性时使用，避免过深层级
• 能用稳定基础类型表达的，不要额外包一层无意义对象
• 禁止为了“以后可能会用”提前塞入无消费方字段

---

类型边界

• 区分“接口原始返回类型”和“页面消费后的展示类型”
• 不要把后端所有字段原样铺到页面组件 props 中
• 页面展示需要格式化、组合、兜底时，应在 utils/ 或 hooks/ 做转换
• 同一个后端实体被多个页面以不同方式使用时，允许定义多个前端视图类型

---

默认值与可选值

• 可选字段要明确标注 ?，不要靠调用方猜测
• 默认值策略必须显式，不要把隐式兜底散落在多个组件里
• 会影响页面分支逻辑的字段，必须明确说明为空时的处理方式
• 列表字段默认值、布尔字段默认值、文本占位值等应在消费层统一处理

---

映射规范

• 映射的目标是让页面更好用，不是机械复制后端结构
• 不要保留“临时透传字段”或无人消费的中间字段
• 若多个页面需要不同数据形状，应该拆成不同类型，而不是堆成一个超大类型
• 时间、金额、状态文案等展示型字段，优先通过派生字段生成，避免在组件内部重复处理

前端类型安全

• 禁止在新增代码中使用无约束的 any
• 对枚举值、状态值、字典值，优先用联合类型或 enum 明确约束
• 组件 Props 类型要最小化，只暴露组件真正需要的数据
• 需要缓存、比较、序列化的数据结构，应保持简单、稳定、可预期

示例

export type KnowledgeListParams = {
  keyword?: string;
  pageNo: number;
  pageSize: number;
};

export type KnowledgeListItem = {
  id: string;
  title: string;
  status: "draft" | "published";
  updatedAt: string;
};