chanjs 2.7.4 → 2.7.6

package/doc/Controller.md

@@ -1,152 +1,223 @@
 # Controller 控制器基类
+
 ## 概述
-`Controller` 是所有业务控制器的基类，继承自 `Container` 容器类，核心作用是提供统一的响应格式封装（成功/失败响应），规范控制器层的返回数据结构，减少重复代码，提升开发效率。
 
-## 依赖说明
-| 依赖模块 | 路径 | 说明 |
-|----------|------|------|
-| `success`/`fail` | `../helper/response.js` | 响应格式封装工具函数，提供标准化的成功/失败响应结构 |
-| `Container` | `./Container.js` | 基础容器类，为控制器提供组件类型标识等能力 |
+`Controller` 是所有业务控制器的基类，继承自 `Container` 容器类，提供统一的响应格式封装（成功/失败响应），规范控制器层的返回数据结构。
+
+## 继承关系
 
-## 类继承关系
 ```
-Container <|-- Controller
+Container <── Controller
 ```
 
 ## 构造函数
-### 语法
+
 ```javascript
 constructor()
 ```
-### 说明
-调用父类 `Container` 的构造函数，并指定组件类型为 `'controller'`，用于容器类对控制器组件的统一管理。
 
-### 示例
+调用父类 `Container` 构造函数，指定组件类型为 `'controller'`。
+
+## 核心方法
+
+### 1. success - 成功响应
+
+封装标准化的成功响应格式。
+
+**语法**
+
 ```javascript
-import Controller from './chanjs/base/Controller.js';
+success({ data, msg = "操作成功" } = {})
+```
+
+**参数**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| data | any | 否 | {} | 响应数据 |
+| msg | string | 否 | "操作成功" | 提示信息 |
 
+**返回值**
+
+```javascript
+{
+  success: true,
+  code: 0,
+  msg: "操作成功",
+  data: { /* 响应数据 */ }
+}
+```
+
+**示例**
+
+```javascript
 class UserController extends Controller {
-  constructor() {
-    super(); // 继承 Controller 构造逻辑
+  async getUser(req, res) {
+    const user = { id: 1, name: "张三" };
+    return this.success({ data: user });
+  }
+  
+  async createUser(req, res) {
+    // 业务逻辑...
+    return this.success({ 
+      data: { id: 100 }, 
+      msg: "创建成功" 
+    });
   }
 }
 ```
 
-## 核心方法
-### 1. 成功响应 - `success(options)`
-封装标准化的成功响应格式，返回统一结构的成功数据。
+### 2. fail - 失败响应
 
-#### 参数说明
-| 参数名 | 类型 | 必传 | 默认值 | 说明 |
-|--------|------|------|--------|------|
-| `options` | `Object` | 否 | `{}` | 响应配置项 |
-| `options.data` | `any` | 否 | - | 响应体数据，可传任意类型（对象、数组、基本类型等） |
-| `options.msg` | `string` | 否 | `"操作成功"` | 响应提示消息 |
+封装标准化的失败响应格式。
 
-#### 返回值
-`Object`：标准化的成功响应对象（结构由 `../helper/response.js` 的 `success` 函数定义）。
+**语法**
 
-#### 示例
 ```javascript
-class UserController extends Controller {
-  async getUserInfo() {
-    const data = { id: 1, name: "张三" };
-    // 返回成功响应，使用默认提示语
-    return this.success({ data });
-    
-    // 自定义提示语
-    // return this.success({ data, msg: "获取用户信息成功" });
-  }
-}
+fail(opts = {})
 ```
 
-### 2. 失败响应 - `fail(options)`
-封装标准化的失败响应格式，返回统一结构的失败数据。
+**参数**
+
+支持两种传参方式：
+
+1. **字符串简写**：直接传入错误提示文案
+2. **对象配置**：传入完整配置对象
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| opts | string \| object | 否 | {} | 错误配置 |
+| opts.msg | string | 否 | "操作失败" | 错误提示 |
+| opts.code | number | 否 | 1008 | 错误码 |
+| opts.data | any | 否 | {} | 附加数据 |
 
-#### 参数说明
-| 参数名 | 类型 | 必传 | 默认值 | 说明 |
-|--------|------|------|--------|------|
-| `options` | `Object` | 否 | `{}` | 响应配置项 |
-| `options.msg` | `string` | 否 | `"操作失败"` | 失败提示消息 |
-| `options.data` | `any` | 否 | `{}` | 失败时附带的补充数据 |
-| `options.code` | `number` | 否 | `201` | 自定义错误码，用于前端区分不同失败场景 |
+**返回值**
 
-#### 返回值
-`Object`：标准化的失败响应对象（结构由 `../helper/response.js` 的 `fail` 函数定义）。
+```javascript
+{
+  success: false,
+  code: 1008,  // 或其他错误码
+  msg: "操作失败",
+  data: {}
+}
+```
+
+**示例**
 
-#### 示例
 ```javascript
 class UserController extends Controller {
-  async updateUserInfo() {
-    try {
-      // 业务逻辑：更新用户信息失败
-      throw new Error("用户ID不存在");
-    } catch (err) {
-      // 返回失败响应，自定义提示语和错误码
+  async deleteUser(req, res) {
+    const { id } = req.params;
+    
+    if (!id) {
+      // 字符串简写
+      return this.fail("用户ID不能为空");
+    }
+    
+    if (id === 1) {
+      // 对象配置，自定义错误码
       return this.fail({ 
-        msg: err.message, 
-        code: 400,
-        data: { userId: 1 } // 附带失败关联的用户ID
+        msg: "该用户不可删除", 
+        code: 1001,
+        data: { userId: id }
       });
-      
-      // 使用默认配置
-      // return this.fail();
     }
+    
+    // 业务逻辑...
+    return this.success({ msg: "删除成功" });
   }
 }
 ```
 
-## 完整使用示例
+## 完整示例
+
 ```javascript
-import Controller from './chanjs/base/Controller.js';
+import { Controller } from 'chanjs';
 
-/**
- * 用户业务控制器
- * 继承 Controller 基类，使用统一响应格式
- */
-class UserController extends Controller {
+export default class UserController extends Controller {
   constructor() {
-    super(); // 必须调用父类构造函数
+    super();
   }
 
-  /**
-   * 获取用户列表
-   * @returns {Object} 成功响应
-   */
-  async getList() {
-    const list = [
+  // 查询用户列表
+  async list(req, res) {
+    const users = [
       { id: 1, name: "张三" },
       { id: 2, name: "李四" }
     ];
+    return this.success({ data: users });
+  }
+
+  // 查询单个用户
+  async detail(req, res) {
+    const { id } = req.params;
+    const user = { id, name: "张三", age: 25 };
+    return this.success({ data: user });
+  }
+
+  // 创建用户
+  async create(req, res) {
+    const { name, email } = req.body;
+    
+    if (!name || !email) {
+      return this.fail({ 
+        msg: "姓名和邮箱不能为空", 
+        code: 1001 
+      });
+    }
+    
+    // 业务逻辑...
+    const newUser = { id: 100, name, email };
     return this.success({ 
-      data: list, 
-      msg: "获取用户列表成功" 
+      data: newUser, 
+      msg: "创建成功" 
     });
   }
 
-  /**
-   * 删除用户
-   * @param {number} id - 用户ID
-   * @returns {Object} 成功/失败响应
-   */
-  async delete(id) {
+  // 更新用户
+  async update(req, res) {
+    const { id } = req.params;
+    const data = req.body;
+    
+    // 业务逻辑...
+    return this.success({ msg: "更新成功" });
+  }
+
+  // 删除用户
+  async delete(req, res) {
+    const { id } = req.params;
+    
     if (!id) {
-      return this.fail({ 
-        msg: "用户ID不能为空", 
-        code: 401 
-      });
+      return this.fail("用户ID不能为空");
     }
     
-    // 模拟删除成功
-    return this.success({ msg: `删除ID为${id}的用户成功` });
+    // 业务逻辑...
+    return this.success({ msg: "删除成功" });
   }
 }
-
-export default UserController;
 ```
 
+## 错误码规范
+
+| 错误码范围 | 说明 |
+|-----------|------|
+| 0 | 成功 |
+| 1xxx | 业务错误 |
+| 5xxx | 系统错误 |
+| 6xxx | 数据库错误 |
+
+常用错误码：
+- `0` - 成功
+- `1008` - 默认业务失败
+- `400` - 参数错误
+- `401` - 未授权
+- `403` - 权限不足
+- `404` - 资源不存在
+- `500` - 系统内部错误
+
 ## 注意事项
-1. 所有自定义控制器必须继承 `Controller` 基类，以保证响应格式的统一性；
-2. `success`/`fail` 方法的参数为可选配置对象，未传参时会使用默认值；
-3. 响应的最终数据结构由 `../helper/response.js` 中的 `success`/`fail` 函数决定，若需调整全局响应格式，建议修改该工具文件；
-4. 错误码 `code` 可根据业务场景自定义扩展（如 400 代表参数错误、404 代表资源不存在等），建议与前端约定统一的错误码规范。
+
+1. 所有自定义控制器必须继承 `Controller` 基类
+2. `success` 方法默认 code 为 `0`，`fail` 方法默认 code 为 `1008`
+3. 响应结构统一为 `{ success, code, msg, data }`
+4. 错误码建议与前端约定统一规范