jeecgboot TS + Vue 模板化 03

jeecgboot

TS对比JS

- 参数类型写在括号里 params: LoginParams - 返回值类型写在 defHttp.post<**T**> 的泛型参数里 - 不写返回值的显式类型 —— TS 会自动推断为 Promise<LoginResultModel> export function loginApi(params: LoginParams, mode: ErrorMessageMode = 'modal') { return defHttp.post<LoginResultModel>( { url: Api.Login, params, }, { errorMessageMode: mode, } ); }

async login( params: LoginParams & { captcha: string; rememberMe: boolean }, //属性合并 mode: ErrorMessageMode = 'modal' ): Promise<GetUserInfoModel | null> {

- params: LoginParams & { captcha: string; rememberMe: boolean } —— 用 & 做"交叉类型"，在现有接口基础上临时扩字段
- async 函数的返回值类型永远是 Promise<真实返回类型>
- const data = await loginApi(...) —— TS 会自动推断 data 为 LoginResultModel

export interface LoginParams { username: string; password: string; captcha?: string; checkKey?: string; remember_me?: boolean; }

- LoginParams —— 你"发出去"给后端的结构
- LoginResultModel —— 后端"返回给你"的结构
- 两者分开写，避免"一个 model 既要当入参又当出参"的模糊语义
- ? 表示"可选字段"，调用方可以不传

const loading = ref<boolean>(false); const loginForm = reactive<LoginParams>({ username: '', password: '', captcha: '', }); async function handleLogin() { loading.value = true; try { // userStore.login 返回 Promise<GetUserInfoModel | null> const userInfo = await userStore.login({ ...loginForm, /// captcha: formModelRef.value?.captcha || '', rememberMe: formModelRef.value?.rememberMe || false, }); notification.success({ message: '登录成功', description: `欢迎回来，${userInfo?.realname}` }); router.push('/home'); } catch (e) { notification.error({ message: '登录失败', description: (e as Error).message }); } finally { loading.value = false; } }

loginForm.username = 'admin'; loginForm.password = '123456';

- ref<boolean>(false) —— 显式给泛型，防止 TS 推断出 never 或 undefined
- reactive<LoginParams>({...}) —— reactive 的类型建议写在尖括号里
- (e as Error) —— catch 里的变量默认是 unknown ，需要断言才能读 .message

captcha: formModelRef.value?.captcha || '',

从formModelRef.value中取出captcha的值，如果取不到或者值为空，则使用空字符串''作为默认值。

|| '' 如果左边的值不存在（或为空值），就使用空字符串作为默认值。

这里的问号?.是可选链运算符（Optional Chaining），作用就是安全地访问对象属性，避免对象为null或undefined时报错。

formModelRef.value == null ? undefined : formModelRef.value.captcha

• 如果formModelRef.value是null或undefined，访问.captcha不会报错，而是返回undefined。
• 如果formModelRef.value有值，则返回它的captcha属性。

let captcha; if (formModelRef.value?.captcha) { captcha = formModelRef.value.captcha; } else { captcha = ''; }

rememberMe: formModelRef.value?.rememberMe || false,

• 尝试取rememberMe的值
• 如果取不到（value是 null/undefined 或rememberMe本身是 falsy），就使用默认值false

泛型 <T> ：你最常打交道的东西

泛型 <T> 可以理解为"类型的参数"。就像函数的参数是"值的参数"：

// 调用处 const result = await defHttp.post<LoginResultModel>({ url: '/login', params, }); post<T = any>( config: AxiosRequestConfig, options?: RequestOptions ): Promise<T> 实际 post( config, options ): Promise<LoginResultModel> return this.request<LoginResultModel>(...)

读这段代码的方式 ：从调用方反着往回看 —— "你在调用方写了 <LoginResultModel> ，这个 T 就顺着 defHttp.post<T> → request<T> → Promise<T> 一路贯穿到底"。

例如：

interface LoginResultModel { token: string; userId: number; }

那么：

const result = await defHttp.post<LoginResultModel>(...)

IDE立刻知道：

result.token result.userId

有提示。

而：

result.username

会直接报错：

Property 'username' does not exist on type 'LoginResultModel'

这就是泛型最大的价值：

src/api/model/baseModel.ts 里有两个你会反复复制的泛型模板：

// 所有"分页查询"都可以用这个作为基础参数 export interface BasicPageParams { page: number; pageSize: number; } // 所有"分页返回"都应该是这种结构： // items 是数据项数组，total 是总数 export interface BasicFetchResult<T> { items: T[]; total: number; }

// src/api/sys/model/departModel.ts import { BasicPageParams, BasicFetchResult } from '/@/api/model/baseModel'; export interface DepartItem { id: string; departName: string; orgCode: string; createTime: string; } export type DepartListParams = BasicPageParams & { departName?: string }; // & 是 交叉类型（Intersection Type） 表示把 BasicPageParams 类型和 { departName?: string } 类型 合并 结果类型拥有两边的所有属性 //? 表示 可选属性 可以有，也可以没有 类型是 string export type DepartListResult = BasicFetchResult<DepartItem>; // ↑ 等价于：{ items: DepartItem[]; total: number }

• interface：更偏“对象结构设计”
• type：更偏“类型运算和组合”

• 写对象结构 → interface
• 做组合/运算 → type
• 不确定 → 默认 interface（更安全）

type User = { name: string; }; type User = { age: number; }; // ❌ 会报错：Cannot redeclare block-scoped variable 'User'. type User = { name: string }; type UserWithAge = User & { age: number }; const u: UserWithAge = { name: 'Alice', age: 18 };

在 JeecgBoot 里，最典型的是 "API model 用 interface，组合/别名用 type"：

// 描述对象 → interface export interface LoginParams { username: string; password: string; } // 描述"一个较长的类型的别名" → type export type ID = string | number; export type DepartListParams = BasicPageParams & { departName?: string }; // ↑ 交叉类型只能用 type

interface：专门描述“对象结构”

type：做“类型组合 / 运算”

• 给一个复杂或常用类型起别名
• 本质是“类型重命名 + 联合类型”

export type ID = string | number;

export type DepartListParams = BasicPageParams & { departName?: string };

👉 把两个类型“合并成一个新类型”

### artial<T> —— 把 T 的所有字段变成可选
源码位置： src/utils/http/axios/index.ts （createAxios 的签名）

function createAxios(opt?: Partial<CreateAxiosOptions>) { return new VAxios(deepMerge({ transform, requestOptions, ... }, opt || {})); }

- CreateAxiosOptions 有一堆字段（ timeout 、 headers 、 transform 、 requestOptions ...）
- 用 Partial<CreateAxiosOptions> 表示"传进来的 opt 可以只包含其中一部分字段"
- 里面再 deepMerge(默认, opt) 把缺的字段用默认值补全

Pick<T, K> —— 从 T 中挑出某些字段

场景：一个 User 有 10 个字段，但某个接口只需要 id 和 username 。

interface User { id: string; username: string; email: string; realname: string; avatar: string; } type LoginUser = Pick<User, 'id' | 'username'>; // 等价于：{ id: string; username: string }

### Omit<T, K> —— 从 T 中去掉某些字段
场景："编辑接口"的参数和"新增接口"很像，只是多了一个 id 。

interface DepartAddParams { departName: string; orgCode: string; parentId?: string; } // 编辑比新增多了一个 id 必填 type DepartEditParams = DepartAddParams & { id: string }; // 或者反过来：从"完整版"里拿掉 id type DepartAddParams2 = Omit<DepartFullParams, 'id'>;

Record<string, T> —— 描述一个"键值对"对象

场景： useModal / useDrawer 的 attrs 传参，或动态表单配置。

// 一个字典：key 是字符串，value 是任意值 const dict: Record<string, any> = { name: 'Jeecg', version: 3, }; // 更具体的约束：某些固定 key type UserFieldMap = Record<'username' | 'password', FormFieldConfig>;

何时允许 any ？何时该封掉？

动态 JSON 对象 （后端返回的 userInfo 就是典型的"结构没定死的东西"）

export interface LoginResultModel { userId: string | number; token: string; role: RoleInfo; userInfo?: any; // ← 后端 userInfo 的字段会变动，标 any 合理 }

- 封装层的顶层 （ defHttp.get<any>(...) —— 你自己调用的时候会把 any 替换成具体类型，所以底层留 any 没大碍）
- 第三方库不提供 d.ts —— 临时声明 declare module 'foo'; 或 const lib: any = require('bar')

### 应该避免 any 的场景（3 个）
1. 业务数据模型 （ LoginParams.username 写成 any ，那和没写 TS 没区别）
2. reactive / ref 状态 （ const loginForm = reactive<any>({}) —— 你会失去所有编辑器提示）
3. 函数返回值 （ async function login(): Promise<any> —— 调用方无法知道拿到的是什么）
最佳实践 ： any 只在"确实无法确定结构"的地方用，其他地方都换成具体类型或泛型。你项目里的 LoginParams 、 LoginResultModel 就是好例子。

一个完整的"从零到页面"的 TS 套路

Step 1. 写 model（数据契约）

// src/api/sys/model/departModel.ts export interface DepartItem { id: string; departName: string; orgCode: string; createTime: string; } export type DepartListParams = BasicPageParams & { departName?: string }; export type DepartListResult = BasicFetchResult<DepartItem>; export interface DepartSaveParams { id?: string; departName: string; orgCode?: string; parentId?: string; }

Step 2. 写 API（带泛型返回值）

// src/api/sys/depart.ts import { defHttp } from '/@/utils/http/axios'; import { DepartListParams, DepartListResult, DepartItem, DepartSaveParams } from './model/departModel'; enum Api { LIST = '/sys/sysDepart/list', ADD = '/sys/sysDepart/add', EDIT = '/sys/sysDepart/edit', DELETE = '/sys/sysDepart/delete', } export const departListApi = (params: DepartListParams) => defHttp.get<DepartListResult>({ url: Api.LIST, params }); export const departAddApi = (params: DepartSaveParams) => defHttp.post({ url: Api.ADD, params }); export const departEditApi = (params: DepartSaveParams) => defHttp.put({ url: Api.EDIT, params }); export const departDeleteApi = (id: string) => defHttp.delete({ url: Api.DELETE, params: { id } });

Step 3. 写 store（把 TS 类型推到状态层）

// src/store/modules/depart.ts // 定义并导出一个 Pinia store 模块 // useDepartStore 是一个函数，调用它可以在组件中拿到 store 实例 export const useDepartStore = defineStore({ // store 的唯一 ID，用于区分不同模块 id: 'depart', // state 是一个函数，返回当前模块的响应式数据对象 state: () => ({ // 当前选中的部门，初始值为 null // TS 类型断言：可能是 DepartItem 类型或者 null currentDepart: null as DepartItem | null, // 部门列表，初始值为空数组 // TS 类型断言：数组中每一项都是 DepartItem 类型 departList: [] as DepartItem[], }), // actions 用来定义方法，可以同步或异步操作 state actions: { // 异步加载部门列表 // params: DepartListParams 类型，通常包含分页或搜索条件 async loadList(params: DepartListParams) { // 调用 API 获取部门列表 // departListApi(params) 返回一个 Promise<DepartItem[]> // await 等待异步结果 const list = await departListApi(params); // 把获取到的部门列表保存到 store 的 state // this.departList 直接访问 store 中的 departList this.departList = list; }, }, });

departList 的类型是：DepartItem[]

• 空数组[]本身 TS 会推断类型为any[]
• 如果不加类型断言，写法如下会报错：

this.departList = await departListApi(params); // TS 可能报类型不匹配

加上as DepartItem[]后：

• departList明确类型，TS 能检查赋值正确性
• 保证数组中元素都是DepartItem，避免后续访问报错

Step 4. 写页面（享受自动提示）

// src/views/system/depart/index.vue const { departList, total } = await departListApi({ page: 1, pageSize: 10, departName: formState.departName, // ← 这里敲 departName. 会出字段提示 });

写完 Step 1 → Step 4 之后， 只要后端的响应结构有变动 ，你改一下 departModel.ts ，所有用到它的地方 TS 都会帮你标出来。这就是 TS 的核心价值。