Vue / 系统课时
建立公共类型
建立公共类型
本课把分页参数、接口响应、下拉选项、字典项和业务实体整理为可复用的 TypeScript 类型,并通过类型检查验证引用关系,避免页面与接口层重复声明或悄悄退化为 any。
学习目标
- 区分真正稳定的公共类型与具体业务类型
- 使用泛型定义分页、响应结果、选项和字典结构
- 通过
vue-tsc验证类型组合是否正确
先划定公共类型边界
公共类型应表达多个模块都会使用、且含义稳定的数据结构,例如分页参数、分页结果和接口响应包装。用户、角色、订单等实体仍应放在各自业务目录中,避免 common.ts 逐渐变成无法维护的类型仓库。
建议将类型按职责拆分为 src/types/common.ts 与 src/types/<domain>.ts。公共文件只提供基础积木,业务文件通过组合和泛型得到最终类型,不直接复制字段。
定义基础类型
创建 src/types/common.ts,集中放置跨模块复用的结构:
export interface ApiResponse<T> {
code: number
message: string
data: T
}
export interface PageQuery {
page: number
pageSize: number
}
export interface PageResult<T> {
list: T[]
total: number
}
export interface SelectOption<Value extends string | number = string> {
label: string
value: Value
disabled?: boolean
}
export interface DictionaryItem<Code extends string = string> {
code: Code
label: string
sort: number
enabled: boolean
}
export type Nullable<T> = T | nullApiResponse<T> 和 PageResult<T> 将变化部分交给泛型参数,调用方既能复用统一外壳,又不会丢失列表元素或响应数据的具体类型。SelectOption 的值限制为字符串或数字,可直接覆盖常见表单控件。
组合业务类型
创建 src/types/user.ts。业务字段只在用户模块声明,分页和响应结构继续复用公共类型:
import type {
ApiResponse,
PageQuery,
PageResult,
SelectOption,
} from './common'
export type UserStatus = 'enabled' | 'disabled'
export interface UserEntity {
id: number
username: string
displayName: string
status: UserStatus
createdAt: string
}
export interface UserListQuery extends PageQuery {
keyword?: string
status?: UserStatus
}
export type UserListResponse = ApiResponse<PageResult<UserEntity>>
export type UserStatusOption = SelectOption<UserStatus>
export const userStatusOptions: UserStatusOption[] = [
{ label: '启用', value: 'enabled' },
{ label: '停用', value: 'disabled' },
]这里把接口返回的时间定义为 string,因为 JSON 传输不会自动生成 JavaScript Date 对象。需要日期运算时,应在业务层显式解析,而不是让类型提前承诺运行时并不存在的对象。
执行类型验证
完成文件后运行项目级类型检查:
pnpm exec vue-tsc --noEmit预期输出:
无错误信息,进程退出码为 0若把选项值改成未声明的 'normal',检查器应报告其不能赋给 UserStatus。这说明公共类型不仅减少声明,也把接口、页面选项和业务状态约束在同一套规则中。
控制类型扩散
不要为了“复用”把所有字段都改成可选,也不要用 Record<string, any> 代替明确实体。创建参数、更新参数、查询参数和服务端实体的必填规则不同,应分别定义 CreateUserInput、UpdateUserInput 等类型。
接口可能返回 null 的字段要显式写为 Nullable<T>;完全未知的外部数据先使用 unknown,完成校验后再收窄。这样可以把不确定性留在边界处,而不是传播到整个项目。