207 lines
4.0 KiB
TypeScript
207 lines
4.0 KiB
TypeScript
/**
|
||
* API 示例代码
|
||
* 展示项目中 API 的编写规范和最佳实践
|
||
*/
|
||
|
||
import { http } from '@/http/http';
|
||
import type { PageParam, PageResult } from '@/api';
|
||
|
||
/**
|
||
* 用户相关类型定义
|
||
*/
|
||
export interface User {
|
||
/** 用户ID */
|
||
id: number;
|
||
/** 用户名 */
|
||
username: string;
|
||
/** 昵称 */
|
||
nickname: string;
|
||
/** 头像 */
|
||
avatar?: string;
|
||
/** 邮箱 */
|
||
email?: string;
|
||
/** 手机号 */
|
||
phone?: string;
|
||
/** 状态（0正常 1禁用） */
|
||
status: number;
|
||
/** 创建时间 */
|
||
createTime: string;
|
||
}
|
||
|
||
/**
|
||
* 用户搜索参数
|
||
*/
|
||
export interface UserParams extends PageParam {
|
||
/** 搜索关键词 */
|
||
keyword?: string;
|
||
/** 状态 */
|
||
status?: number;
|
||
/** 开始时间 */
|
||
startTime?: string;
|
||
/** 结束时间 */
|
||
endTime?: string;
|
||
}
|
||
|
||
/**
|
||
* 创建用户参数
|
||
*/
|
||
export interface CreateUserParams {
|
||
/** 用户名 */
|
||
username: string;
|
||
/** 密码 */
|
||
password: string;
|
||
/** 昵称 */
|
||
nickname: string;
|
||
/** 邮箱 */
|
||
email?: string;
|
||
/** 手机号 */
|
||
phone?: string;
|
||
}
|
||
|
||
/**
|
||
* 更新用户参数
|
||
*/
|
||
export interface UpdateUserParams extends Partial<CreateUserParams> {
|
||
/** 用户ID */
|
||
id: number;
|
||
/** 状态 */
|
||
status?: number;
|
||
}
|
||
|
||
/**
|
||
* 用户相关 API
|
||
*/
|
||
|
||
// ✅ 正确示例：获取用户列表（分页）
|
||
/**
|
||
* 获取用户列表
|
||
* @param params 搜索参数
|
||
* @param params.page 当前页码（默认1）
|
||
* @param params.size 每页数量（默认10）
|
||
* @param params.keyword 搜索关键词（可选）
|
||
* @param params.status 状态筛选（可选）
|
||
* @returns 用户列表
|
||
*/
|
||
export function getUserList(params?: UserParams) {
|
||
return http.get<PageResult<User[]>>('/api/users', params);
|
||
}
|
||
|
||
// ✅ 正确示例：获取用户详情
|
||
/**
|
||
* 获取用户详情
|
||
* @param id 用户ID
|
||
* @returns 用户详情
|
||
*/
|
||
export function getUserById(id: number) {
|
||
return http.get<User>(`/api/users/${id}`);
|
||
}
|
||
|
||
// ✅ 正确示例：创建用户
|
||
/**
|
||
* 创建用户
|
||
* @param data 用户信息
|
||
* @returns 创建结果
|
||
*/
|
||
export function createUser(data: CreateUserParams) {
|
||
return http.post<User>('/api/users', data);
|
||
}
|
||
|
||
// ✅ 正确示例：更新用户
|
||
/**
|
||
* 更新用户信息
|
||
* @param data 用户信息
|
||
* @returns 更新结果
|
||
*/
|
||
export function updateUser(data: UpdateUserParams) {
|
||
return http.put<User>(`/api/users/${data.id}`, data);
|
||
}
|
||
|
||
// ✅ 正确示例：删除用户
|
||
/**
|
||
* 删除用户
|
||
* @param id 用户ID
|
||
* @returns 删除结果
|
||
*/
|
||
export function deleteUser(id: number) {
|
||
return http.delete(`/api/users/${id}`);
|
||
}
|
||
|
||
// ✅ 正确示例：批量删除用户
|
||
/**
|
||
* 批量删除用户
|
||
* @param ids 用户ID列表
|
||
* @returns 删除结果
|
||
*/
|
||
export function batchDeleteUsers(ids: number[]) {
|
||
return http.post('/api/users/batch-delete', { ids });
|
||
}
|
||
|
||
// ✅ 正确示例：重置用户密码
|
||
/**
|
||
* 重置用户密码
|
||
* @param id 用户ID
|
||
* @returns 操作结果
|
||
*/
|
||
export function resetUserPassword(id: number) {
|
||
return http.post(`/api/users/${id}/reset-password`);
|
||
}
|
||
|
||
// ❌ 错误示例：没有中文注释
|
||
export function getUsers(params?: any) {
|
||
return http.get('/api/users', params);
|
||
}
|
||
|
||
// ❌ 错误示例：命名不规范
|
||
export function users_list() {
|
||
return http.get('/api/users');
|
||
}
|
||
|
||
// ❌ 错误示例：没有类型约束
|
||
export function createNewUser(data: any) {
|
||
return http.post('/api/users', data);
|
||
}
|
||
|
||
/**
|
||
* 其他业务模块 API 示例
|
||
*/
|
||
|
||
// 角色相关 API
|
||
export interface Role {
|
||
id: number;
|
||
name: string;
|
||
code: string;
|
||
description?: string;
|
||
status: number;
|
||
}
|
||
|
||
export function getRoleList() {
|
||
return http.get<Role[]>('/api/roles');
|
||
}
|
||
|
||
// 权限相关 API
|
||
export interface Permission {
|
||
id: number;
|
||
name: string;
|
||
code: string;
|
||
type: number;
|
||
parentId?: number;
|
||
}
|
||
|
||
export function getPermissionTree() {
|
||
return http.get<Permission[]>('/api/permissions/tree');
|
||
}
|
||
|
||
// 部门相关 API
|
||
export interface Department {
|
||
id: number;
|
||
name: string;
|
||
parentId?: number;
|
||
sort: number;
|
||
status: number;
|
||
children?: Department[];
|
||
}
|
||
|
||
export function getDepartmentTree() {
|
||
return http.get<Department[]>('/api/departments/tree');
|
||
}
|