mdk-skills 2.1.3

package/.claude/skills/fe-biz-patterns/references/service-layer.md

@@ -0,0 +1,198 @@
+# Service 层封装方案
+
+## 概述
+
+基于 axios 的请求层封装，核心模式：
+
+1. **Request 类 + 单例** — 封装 axios 实例，统一配置和拦截器
+2. **按业务域拆分模块** — `modules/[domain].ts`，类型与函数共置
+3. **config 集中管理** — baseURL、超时、状态码映射统一维护
+
+## 目录结构
+
+```
+src/service/
+  index.ts           -- 统一导出
+  request/
+    config.ts        -- 配置集中管理
+    index.ts         -- Request 类（axios 封装）
+  modules/
+    home.ts          -- 首页 API
+    city.ts          -- 城市 API
+```
+
+## Request 类封装
+
+```ts
+class Request {
+  private instance: AxiosInstance
+
+  constructor() {
+    this.instance = axios.create({
+      baseURL: config.baseURL,
+      timeout: config.timeout,
+      headers: config.headers,
+    })
+  }
+
+  public get<T>(url, params?, options?): Promise<T>
+  public post<T>(url, data?, options?): Promise<T>
+  public put<T>(url, data?, options?): Promise<T>
+  public delete<T>(url, params?, options?): Promise<T>
+}
+
+export const request = new Request()
+```
+
+关键设计点：
+
+- **单例模式**：整个应用共享一个 Request 实例，避免重复创建
+- **泛型方法**：`get<T>` 返回 `Promise<T>`，调用方通过类型参数控制返回值类型
+- **RequestOptions**：扩展 `AxiosRequestConfig`，预留 `showLoading`、`showError` 等业务字段
+
+## 拦截器（可选启用）
+
+拦截器默认不激活，需要时显式调用 `request.enableInterceptors()`：
+
+```ts
+class Request {
+  /** 启用拦截器：token 注入 + 统一错误处理 */
+  enableInterceptors() {
+    // 请求拦截器：自动注入 token
+    this.instance.interceptors.request.use((config) => {
+      const token = localStorage.getItem('token')
+      if (token) {
+        config.headers.Authorization = `Bearer ${token}`
+      }
+      return config
+    })
+
+    // 响应拦截器：解包数据 + 统一错误提示
+    this.instance.interceptors.response.use(
+      (response) => {
+        const { code, message, data } = response.data
+        if (code === 0) return data  // 成功：直接返回业务数据
+        console.error('请求失败:', message)
+        return Promise.reject(new Error(message))
+      },
+      (error) => {
+        if (error.response) {
+          console.error(statusCodeMap[error.response.status] || '网络请求失败')
+        } else {
+          console.error('网络连接失败')
+        }
+        return Promise.reject(error)
+      },
+    )
+  }
+}
+```
+
+启用后，API 函数的写法会简化——不再需要手动解 `res.data`，因为响应拦截器已经解了一层。
+
+## Config 集中管理
+
+```ts
+// src/service/request/config.ts
+export interface RequestConfig {
+  baseURL: string
+  timeout: number
+  headers?: Record<string, string>
+}
+
+export const config: RequestConfig = {
+  baseURL: 'http://xxx/api',
+  timeout: 10000,
+  headers: { 'Content-Type': 'application/json' },
+}
+
+export const statusCodeMap: Record<number, string> = {
+  400: '请求参数错误',
+  401: '未授权，请登录',
+  403: '拒绝访问',
+  404: '请求地址不存在',
+  500: '服务器内部错误',
+}
+```
+
+多 API 源时，在 config 中添加对应配置对象，Request 类中用单独 instance 隔离：
+
+```ts
+export const mapConfig = {
+  baseURL: '/api/map',
+  key: 'xxx',
+}
+
+// request/index.ts
+class Request {
+  private mapInstance: AxiosInstance | null = null
+
+  public mapGet<T>(url, params?): Promise<T> {
+    if (!this.mapInstance) {
+      this.mapInstance = axios.create({ baseURL: mapConfig.baseURL, timeout: config.timeout })
+    }
+    return this.mapInstance.get(url, { params })
+  }
+}
+```
+
+## API 模块组织
+
+### 按业务域拆分
+
+```ts
+// src/service/modules/home.ts
+import { request } from '../request'
+
+// 类型定义与 API 函数共置
+export interface HouseListItem { /* ... */ }
+
+export const getHotSuggests = async () => {
+  const res = await request.get('/home/hotSuggests')
+  return res.data
+}
+
+export const getHouseList = async (page = 1) => {
+  const res = await request.get('/home/houselist', { page })
+  return res.data
+}
+```
+
+### 规则
+
+| 原则 | 说明 |
+|------|------|
+| 一域一文件 | 每个业务模块一个文件，命名与后端资源对应 |
+| 类型共置 | 接口响应类型定义在 API 函数同一文件，就近维护 |
+| 函数即接口 | 每个 API 导出一个 async 函数，参数即业务参数 |
+| 统一导出 | `service/index.ts` 只导出 request 实例和核心类型，modules 由消费方按需 import |
+
+## View 层消费方式
+
+```ts
+import { getHotSuggests } from '@/service/modules/home'
+
+onMounted(async () => {
+  const res = await getHotSuggests()
+  hotSuggests.value = res.data || []
+})
+```
+
+或通过 store 间接调用：
+
+```ts
+// store 中调用 service
+const fetchHotSuggests = async () => {
+  const res = await getHotSuggests()
+  hotSuggests.value = res.data || []
+}
+
+// view 中调用 store action
+onMounted(() => store.fetchHotSuggests())
+```
+
+## 注意事项
+
+1. **拦截器启用时机**：`enableInterceptors()` 应在应用初始化时（如 `main.ts`）调用一次，避免重复注册
+2. **响应拦截器副作用**：启用后 API 函数返回的是解包后的业务数据，而非完整 AxiosResponse，与之配套的 store 逻辑需要同步调整
+3. **泛型参数**：`request.get<T>` 的 `T` 只是类型标注，不会在运行时做校验，后端返回格式异常仍需前端容错