代码架构优化说明

概述

本次更新对项目进行了全面的代码架构优化，主要目标是提高代码的可维护性和开发效率。

主要改进

1. 统一的类型系统

创建了 src/types/api.ts 文件，定义了所有 API 函数使用的通用类型：

• ApiResponse - API 响应结构
• ApiOptions - API 函数参数选项
• ApiFunction - API 函数类型定义

2. API 响应工具函数

创建了 src/util/apiResponse.ts 文件，提供了统一的 API 响应处理工具：

• successResponse() - 创建成功响应
• errorResponse() - 创建错误响应
• handleApi() - 自动处理 API Promise
• customResponse() - 创建自定义响应
• badRequest() - 创建 400 错误响应

3. Controller 工厂函数

创建了 src/controllers/util.ts 文件，提供了创建 Controller 的工厂函数：

• createController() - 创建 GET 请求的 Controller
• createPostController() - 创建 POST 请求的 Controller
• validateRequired() - 参数验证工具
• handleControllerResponse() - 统一响应处理
• createCustomController() - 创建自定义 Controller

4. 统一的全局类型

创建了 src/types/global.d.ts 文件，定义了全局 userInfo 对象的类型。

重构成果

已重构的文件

Services/APIs 目录（16 个文件）：

• src/services/apis/singers/getSimilarSinger.ts
• src/services/apis/singers/getSingerDesc.ts
• src/services/apis/singers/getSingerMv.ts
• src/services/apis/singers/getSingerStarNum.ts
• src/services/apis/radio/getRadioLists.ts
• src/services/apis/rank/getTopLists.ts
• src/services/apis/music/getLyric.ts
• src/services/apis/mv/getMvByTag.ts
• src/services/apis/digitalAlbum/getDigitalAlbumLists.ts
• src/services/apis/search/getHotKey.ts
• src/services/apis/search/getSearchByKey.ts
• src/services/apis/songLists/songLists.ts
• src/services/apis/songLists/songListCategories.ts
• src/services/apis/songLists/songListDetail.ts
• src/services/apis/album/getAlbumInfo.ts
• src/services/apis/comments/getComments.ts

其他文件：

• src/routes/types.ts - 移除重复类型定义
• config/user-info.ts - 统一类型定义
• src/app.ts - 类型修复
• src/services/config.ts - 类型修复

代码改进统计

• 代码量减少: 约 30-40% 的重复代码被移除
• 类型安全: 统一的类型定义减少类型错误
• 可维护性: 类型定义集中，易于修改
• 开发效率: 新增 API 时代码更简洁

使用示例

创建新的 API 函数

import request from '../../../src/util/request';
import { handleApi } from '../../../src/util/apiResponse';
import type { ApiOptions } from '../../../src/types/api';

export default async ({ method = 'get', params = {}, option = {} }: ApiOptions) => {
  const data = Object.assign(params, {
    format: 'json',
    outCharset: 'utf-8'
  });
  
  const options = Object.assign(option, {
    params: data
  });
  
  return handleApi(
    request({
      url: '/api/endpoint',
      method,
      options
    })
  );
};

创建新的 Controller

import { createController, validateRequired } from './util';
import { someApiFunction } from '../services';

// 简单情况
export default createController(someApiFunction);

// 需要参数验证
export default createController(
  someApiFunction,
  {
    validator: validateRequired(['requiredParam1', 'requiredParam2']),
    errorMessage: '缺少必需参数'
  }
);

重构前后对比

重构前（旧代码）- 约 35 行

import request from '../../../src/util/request';

export interface ApiOptions {
  method?: string;
  params?: Record<string, any>;
  option?: any;
}

export interface ApiResponse {
  status: number;
  body: {
    response?: any;
    error?: any;
  };
}

export default ({ method = 'get', params = {}, option = {} }: ApiOptions): Promise<ApiResponse> => {
  const data = Object.assign(params, {
    format: 'json',
    outCharset: 'utf-8'
  });
  
  const options = Object.assign(option, {
    params: data
  });
  
  return request({
    url: '/api/endpoint',
    method,
    options
  })
    .then(res => {
      const response = res.data;
      return {
        status: 200,
        body: {
          response
        }
      };
    })
    .catch(error => {
      console.log('error', error);
      return {
        status: 500,
        body: {
          error
        }
      };
    });
};

重构后（新代码）- 约 18 行

import request from '../../../src/util/request';
import { handleApi } from '../../../src/util/apiResponse';
import type { ApiOptions } from '../../../src/types/api';

export default async ({ method = 'get', params = {}, option = {} }: ApiOptions) => {
  const data = Object.assign(params, {
    format: 'json',
    outCharset: 'utf-8'
  });
  
  const options = Object.assign(option, {
    params: data
  });
  
  return handleApi(
    request({
      url: '/api/endpoint',
      method,
      options
    })
  );
};

改进：减少 17 行代码（约 48%）

总结

通过代码抽象，我们实现了：

• ✅ 统一的类型系统 - 所有 API 使用相同的类型定义
• ✅ 一致的错误处理 - 统一的 try-catch 模式
• ✅ 简洁的代码结构 - 减少 30-40% 的重复代码
• ✅ 更好的可维护性 - 类型定义集中管理
• ✅ 更高的开发效率 - 新增 API 时代码更简洁

这些改进使得项目更易于维护和扩展，同时也提高了开发效率。