shop-wx/doc/examples/api-example.ts

/**
 * 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');
}