chanjs 2.7.4 → 2.7.5

package/doc/QuickStart.md

@@ -0,0 +1,116 @@
+# ChanJS 快速入门
+
+## 安装
+
+```bash
+npm install chanjs
+```
+
+## 最小化启动
+
+### 1. 创建入口文件 `index.js`
+
+```javascript
+import Chan from 'chanjs';
+
+const app = new Chan();
+await app.start();
+app.run(port => {
+  console.log(`服务启动在端口 ${port}`);
+});
+```
+
+### 2. 创建配置文件 `config/index.js`
+
+```javascript
+export default {
+  PORT: 3000,
+  NODE_ENV: 'dev',
+  
+  // 数据库配置（可选）
+  db: [{
+    key: 'default',
+    client: 'mysql2',
+    connection: {
+      host: '127.0.0.1',
+      user: 'root',
+      password: '',
+      database: 'test'
+    }
+  }],
+  
+  // 模块列表
+  modules: ['web', 'api']
+};
+```
+
+### 3. 创建模块目录结构
+
+```
+app/
+├── modules/
+│   ├── web/
+│   │   ├── controller/
+│   │   │   └── IndexController.js
+│   │   └── router.js
+│   └── api/
+│       ├── controller/
+│       │   └── UserController.js
+│       └── router.js
+```
+
+### 4. 创建控制器
+
+```javascript
+// app/modules/api/controller/UserController.js
+import { Controller } from 'chanjs';
+
+export default class UserController extends Controller {
+  async getUser(req, res) {
+    const { id } = req.params;
+    // 业务逻辑
+    return this.success({ data: { id, name: '张三' } });
+  }
+}
+```
+
+### 5. 创建路由
+
+```javascript
+// app/modules/api/router.js
+import { loader } from 'chanjs';
+
+export default async function(app, router, config) {
+  const userCtrl = await loader.loadController('api', 'UserController');
+  
+  router.get('/user/:id', userCtrl.getUser);
+}
+```
+
+## 访问测试
+
+```bash
+curl http://localhost:3000/api/user/1
+```
+
+响应：
+```json
+{
+  "success": true,
+  "code": 0,
+  "msg": "操作成功",
+  "data": {
+    "id": "1",
+    "name": "张三"
+  }
+}
+```
+
+## 下一步
+
+- [Controller 控制器](./Controller.md) - 学习控制器编写规范
+- [Service 服务层](./Service.md) - 业务逻辑层使用
+- [Repository 数据层](./Repository.md) - 数据库操作
+- [Cache 缓存](./Cache.md) - 缓存使用
+- [Common 公共配置](./Common.md) - 全局配置说明
+- [Help API 参考](./Help.md) - 完整 API 文档

package/doc/Repository.md

@@ -0,0 +1,560 @@
+# Repository 数据访问层
+
+## 概述
+
+`Repository` 是数据访问层基类，继承自 `Container`，封装了常用的数据库 CRUD 操作。基于 Knex.js 构建，提供统一的查询接口和错误处理。
+
+## 继承关系
+
+```
+Container <── Repository
+```
+
+## 构造函数
+
+```javascript
+constructor(tableName, dbName = 'default')
+```
+
+**参数**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| tableName | string | 是 | - | 数据库表名 |
+| dbName | string | 否 | 'default' | 数据库连接名称 |
+
+**示例**
+
+```javascript
+import { Repository } from 'chanjs';
+
+class UserRepo extends Repository {
+  constructor() {
+    super('users', 'default');
+  }
+}
+
+export default new UserRepo();
+```
+
+## 核心方法
+
+### 1. all - 查询全部
+
+```javascript
+all({ query, sort, fields, limit })
+```
+
+**参数**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| query | object | 否 | {} | 查询条件 |
+| sort | object | 否 | {} | 排序规则 |
+| fields | string[] | 否 | [] | 返回字段，空数组返回全部 |
+| limit | number | 否 | 1000 | 返回数量上限 |
+
+**返回值**
+
+```javascript
+{
+  success: true,
+  code: 0,
+  msg: '操作成功',
+  data: [...]
+}
+```
+
+**示例**
+
+```javascript
+// 查询所有用户
+const users = await userRepo.all();
+
+// 条件查询 + 排序
+const activeUsers = await userRepo.all({
+  query: { status: 1 },
+  sort: { createdAt: 'desc' },
+  fields: ['id', 'name', 'email'],
+  limit: 100
+});
+```
+
+### 2. find - 分页查询
+
+```javascript
+find({ query, sort, fields, limit, offset })
+```
+
+**参数**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| query | object | 否 | {} | 查询条件 |
+| sort | object | 否 | {} | 排序规则 |
+| fields | string[] | 否 | [] | 返回字段 |
+| limit | number | 否 | 10 | 每页数量 |
+| offset | number | 否 | 0 | 偏移量 |
+
+**返回值**
+
+```javascript
+{
+  success: true,
+  code: 0,
+  msg: '操作成功',
+  data: {
+    list: [...],
+    total: 100,
+    limit: 10,
+    offset: 0
+  }
+}
+```
+
+**示例**
+
+```javascript
+const result = await userRepo.find({
+  query: { status: 1 },
+  sort: { id: 'desc' },
+  limit: 20,
+  offset: 40  // 第 3 页
+});
+```
+
+### 3. findOne - 查询单条
+
+```javascript
+findOne({ query, fields })
+```
+
+**参数**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| query | object | 是 | - | 查询条件 |
+| fields | string[] | 否 | [] | 返回字段 |
+
+**返回值**
+
+```javascript
+{
+  success: true,
+  code: 0,
+  msg: '操作成功',
+  data: { ... }  // 或 null
+}
+```
+
+**示例**
+
+```javascript
+const user = await userRepo.findOne({
+  query: { email: 'test@example.com' }
+});
+```
+
+### 4. findById - 根据 ID 查询
+
+```javascript
+findById(id, { fields })
+```
+
+**参数**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| id | number/string | 是 | - | 记录 ID |
+| fields | string[] | 否 | [] | 返回字段 |
+
+**示例**
+
+```javascript
+const user = await userRepo.findById(1);
+```
+
+### 5. insert - 插入记录
+
+```javascript
+insert(data)
+```
+
+**参数**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| data | object | 是 | 插入的数据 |
+
+**返回值**
+
+```javascript
+{
+  success: true,
+  code: 0,
+  msg: '操作成功',
+  data: { insertId: 1 }
+}
+```
+
+**示例**
+
+```javascript
+const result = await userRepo.insert({
+  name: '张三',
+  email: 'zhangsan@example.com',
+  status: 1
+});
+```
+
+### 6. insertMany - 批量插入
+
+```javascript
+insertMany(records)
+```
+
+**参数**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| records | object[] | 是 | 记录数组 |
+
+**示例**
+
+```javascript
+await userRepo.insertMany([
+  { name: '张三', email: 'zhangsan@example.com' },
+  { name: '李四', email: 'lisi@example.com' }
+]);
+```
+
+### 7. updateById - 根据 ID 更新
+
+```javascript
+updateById(id, data)
+```
+
+**参数**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| id | number/string | 是 | 记录 ID |
+| data | object | 是 | 更新的数据 |
+
+**返回值**
+
+```javascript
+{
+  success: true,
+  code: 0,
+  msg: '操作成功',
+  data: { affectedRows: 1 }
+}
+```
+
+**示例**
+
+```javascript
+await userRepo.updateById(1, {
+  name: '张三丰',
+  updatedAt: new Date()
+});
+```
+
+### 8. updateByQuery - 条件更新
+
+```javascript
+updateByQuery({ query, data })
+```
+
+**参数**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| query | object | 是 | 更新条件 |
+| data | object | 是 | 更新的数据 |
+
+**示例**
+
+```javascript
+await userRepo.updateByQuery({
+  query: { status: 0 },
+  data: { status: 1 }
+});
+```
+
+### 9. del - 条件删除
+
+```javascript
+del(query)
+```
+
+**参数**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| query | object | 是 | 删除条件 |
+
+**返回值**
+
+```javascript
+{
+  success: true,
+  code: 0,
+  msg: '操作成功',
+  data: { affectedRows: 1 }
+}
+```
+
+**示例**
+
+```javascript
+await userRepo.del({ status: -1 });
+```
+
+### 10. deleteById - 根据 ID 删除
+
+```javascript
+deleteById(id)
+```
+
+**示例**
+
+```javascript
+await userRepo.deleteById(1);
+```
+
+### 11. deleteMany - 批量删除
+
+```javascript
+deleteMany(ids)
+```
+
+**参数**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| ids | array | 是 | ID 数组 |
+
+**示例**
+
+```javascript
+await userRepo.deleteMany([1, 2, 3]);
+```
+
+### 12. count - 统计数量
+
+```javascript
+count(query)
+```
+
+**参数**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| query | object | 否 | {} | 查询条件 |
+
+**返回值**
+
+```javascript
+{
+  success: true,
+  code: 0,
+  msg: '操作成功',
+  data: { count: 100 }
+}
+```
+
+**示例**
+
+```javascript
+const result = await userRepo.count({ status: 1 });
+console.log(result.data.count);  // 100
+```
+
+### 13. exists - 判断是否存在
+
+```javascript
+exists(query)
+```
+
+**参数**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| query | object | 是 | 查询条件 |
+
+**返回值**
+
+```javascript
+{
+  success: true,
+  code: 0,
+  msg: '操作成功',
+  data: { exists: true }
+}
+```
+
+**示例**
+
+```javascript
+const result = await userRepo.exists({ email: 'test@example.com' });
+if (result.data.exists) {
+  console.log('用户已存在');
+}
+```
+
+### 14. join - 联表查询
+
+```javascript
+join({ joinTable, localField, foreignField, fields, query, sort })
+```
+
+**参数**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| joinTable | string | 是 | - | 关联表名 |
+| localField | string | 是 | - | 本表关联字段 |
+| foreignField | string | 是 | - | 关联表字段 |
+| fields | string[] | 否 | [] | 返回字段 |
+| query | object | 否 | {} | 查询条件 |
+| sort | object | 否 | {} | 排序规则 |
+
+**示例**
+
+```javascript
+const result = await userRepo.join({
+  joinTable: 'orders',
+  localField: 'id',
+  foreignField: 'userId',
+  fields: ['users.name', 'orders.total'],
+  query: { 'orders.status': 1 }
+});
+```
+
+### 15. stats - 统计总数和今日新增
+
+```javascript
+stats(dateField = 'createdAt')
+```
+
+**参数**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| dateField | string | 否 | 'createdAt' | 日期字段名 |
+
+**返回值**
+
+```javascript
+{
+  success: true,
+  code: 0,
+  msg: '操作成功',
+  data: {
+    total: 1000,
+    today: 50
+  }
+}
+```
+
+**示例**
+
+```javascript
+const result = await userRepo.stats('createdAt');
+console.log(`总数：${result.data.total}，今日新增：${result.data.today}`);
+```
+
+## 查询条件语法
+
+Repository 支持灵活的查询条件语法：
+
+### 等值查询
+
+```javascript
+{ field: value }
+```
+
+### 范围查询
+
+```javascript
+{ field: { $gt: 10, $lt: 20 } }  // 大于 10 且小于 20
+{ field: { $gte: 10, $lte: 20 } } // 大于等于 10 且小于等于 20
+```
+
+### 模糊查询
+
+```javascript
+{ field: { $like: '%keyword%' } }
+```
+
+### IN 查询
+
+```javascript
+{ field: { $in: [1, 2, 3] } }
+```
+
+### NOT 查询
+
+```javascript
+{ field: { $ne: value } }
+```
+
+### NULL 查询
+
+```javascript
+{ field: { $null: true } }   // IS NULL
+{ field: { $notNull: true } } // IS NOT NULL
+```
+
+## 完整示例
+
+```javascript
+import { Repository } from 'chanjs';
+
+class UserRepo extends Repository {
+  constructor() {
+    super('users', 'default');
+  }
+
+  // 自定义业务方法
+  async findActiveUsers() {
+    return this.all({
+      query: { status: 1 },
+      sort: { createdAt: 'desc' }
+    });
+  }
+
+  async findByEmail(email) {
+    return this.findOne({
+      query: { email }
+    });
+  }
+
+  async deactivateUser(id) {
+    return this.updateById(id, {
+      status: 0,
+      deactivatedAt: new Date()
+    });
+  }
+}
+
+export default new UserRepo();
+```
+
+## 注意事项
+
+1. Repository 封装了 Knex.js，所有查询都会经过参数校验和 SQL 注入防护
+2. 返回结果统一使用 `{ success, code, msg, data }` 格式
+3. 错误会自动转换为框架标准错误类
+4. 支持多数据库连接，通过构造函数的 `dbName` 参数指定
+5. 日期字段会自动进行格式化处理
+
+## 相关文档
+
+- [QuickStart](./QuickStart.md) - 快速入门
+- [Controller](./Controller.md) - 控制器基类
+- [Service](./Service.md) - 服务基类
+- [Cache](./Cache.md) - 缓存工具
+- [Common](./Common.md) - 公共工具模块