yuxuanhui
91861565bb
- Introduced API guidelines for interface contracts and request handling. - Added design tokens usage guidelines for consistent styling across the project. - Established DTO guidelines for defining request parameters and response data types. - Created frontend structure guidelines to clarify directory organization and code placement rules. - Compiled a comprehensive frontend development guideline document covering various aspects of the development process. - Implemented quality guidelines to ensure code maintainability and adherence to best practices.
74 lines
2.5 KiB
Markdown
74 lines
2.5 KiB
Markdown
# 类型定义规范
|
|
|
|
> 前端请求参数、响应数据类型以及页面数据模型的定义规范。
|
|
|
|
---
|
|
|
|
## 命名原则
|
|
|
|
- 类型名要体现用途，例如 `LoginParams`、`OrderListItem`、`UserDetailResponse`
|
|
- 优先使用业务语义命名，不用后端传输层术语硬套前端场景
|
|
- 名称要与实际使用场景一致，不要出现“通用类型”却只服务单一页面的情况
|
|
- 页面私有类型优先就近定义在页面目录；全局复用类型再抽到公共位置
|
|
|
|
---
|
|
|
|
## 字段设计原则
|
|
|
|
- 只保留当前页面、组件、Hook 真实需要的字段
|
|
- 字段语义必须单一明确，不要一个字段承担多种含义
|
|
- 嵌套对象只在确实提升可读性时使用，避免过深层级
|
|
- 能用稳定基础类型表达的，不要额外包一层无意义对象
|
|
- 禁止为了“以后可能会用”提前塞入无消费方字段
|
|
|
|
---
|
|
|
|
## 类型边界
|
|
|
|
- 区分“接口原始返回类型”和“页面消费后的展示类型”
|
|
- 不要把后端所有字段原样铺到页面组件 props 中
|
|
- 页面展示需要格式化、组合、兜底时，应在 `utils/` 或 `hooks/` 做转换
|
|
- 同一个后端实体被多个页面以不同方式使用时，允许定义多个前端视图类型
|
|
|
|
---
|
|
|
|
## 默认值与可选值
|
|
|
|
- 可选字段要明确标注 `?`，不要靠调用方猜测
|
|
- 默认值策略必须显式，不要把隐式兜底散落在多个组件里
|
|
- 会影响页面分支逻辑的字段，必须明确说明为空时的处理方式
|
|
- 列表字段默认值、布尔字段默认值、文本占位值等应在消费层统一处理
|
|
|
|
---
|
|
|
|
## 映射规范
|
|
|
|
- 映射的目标是让页面更好用，不是机械复制后端结构
|
|
- 不要保留“临时透传字段”或无人消费的中间字段
|
|
- 若多个页面需要不同数据形状，应该拆成不同类型，而不是堆成一个超大类型
|
|
- 时间、金额、状态文案等展示型字段，优先通过派生字段生成，避免在组件内部重复处理
|
|
|
|
## 前端类型安全
|
|
|
|
- 禁止在新增代码中使用无约束的 `any`
|
|
- 对枚举值、状态值、字典值，优先用联合类型或 `enum` 明确约束
|
|
- 组件 Props 类型要最小化，只暴露组件真正需要的数据
|
|
- 需要缓存、比较、序列化的数据结构，应保持简单、稳定、可预期
|
|
|
|
## 示例
|
|
|
|
```ts
|
|
export type KnowledgeListParams = {
|
|
keyword?: string;
|
|
pageNo: number;
|
|
pageSize: number;
|
|
};
|
|
|
|
export type KnowledgeListItem = {
|
|
id: string;
|
|
title: string;
|
|
status: "draft" | "published";
|
|
updatedAt: string;
|
|
};
|
|
```
|