签入版本

2026-09-12 23:12:15 +08:00
commit 91998056ca
1841 changed files with 341325 additions and 0 deletions
@@ -0,0 +1,352 @@
+# 第四章 架构设计 - 扩展性设计
+
+## 4.1 扩展性设计原则
+
+项目遵循开闭原则（OCP）：对扩展开放，对修改关闭。新功能通过添加新模块实现，而非修改现有代码。系统通过 Django App 机制、代码生成器、模板定制等方式提供扩展能力。
+
+## 4.2 Django App 机制
+
+### 4.2.1 模块化设计
+
+每个业务模块独立为一个 Django App，可独立开发、测试和部署：
+
+```
+application/
+    +-- example/          # 案例模块
+    |   +-- __init__.py
+    |   +-- apps.py       # 应用配置
+    |   +-- models.py     # 数据模型
+    |   +-- forms.py      # 表单验证
+    |   +-- services.py   # 业务逻辑
+    |   +-- views.py      # 视图处理
+    |   +-- urls.py       # 路由配置
+    |
+    +-- user/             # 用户模块
+    +-- role/             # 角色模块
+    +-- ...               # 其他模块
+```
+
+### 4.2.2 应用注册
+
+新模块需要在 `application/settings.py` 中注册：
+
+```python
+INSTALLED_APPS = [
+    # ... 其他应用
+    'application.example',  # 注册案例模块
+]
+```
+
+### 4.2.3 路由注册
+
+新模块需要在 `application/urls.py` 中注册路由：
+
+```python
+urlpatterns = [
+    # ... 其他路由
+    path('example/', include('application.example.urls')),
+]
+```
+
+## 4.3 代码生成器
+
+### 4.3.1 生成器概述
+
+代码生成器是 核心功能，通过数据库表定义自动生成完整的 CRUD 模块，包括：
+
+- 后端：Model、Form、Service、View、URL、Admin
+- 前端：Vue 页面、API 模块、表格列配置、查询表单配置
+- 数据库：迁移文件、菜单记录、权限节点
+
+### 4.3.2 使用方式
+
+```bash
+# 从数据库表生成配置
+python generator.py django_<table>
+
+# 从配置文件生成代码
+python generator.py --config config.json
+
+# 仅预览配置，不生成代码
+python generator.py django_<table> --dry-run
+```
+
+### 4.3.3 生成器工作流程
+
+```
+1. 解析数据库表结构
+   +-- 获取字段名、类型、注释、长度、索引
+   +-- 启发式分类字段（图片、富文本、状态、排序等）
+   |
+   v
+2. 生成配置文件 (config.json)
+   +-- 模块名称、表名、字段定义
+   +-- 前端组件类型、验证规则
+   |
+   v
+3. 渲染 Jinja2 模板
+   +-- 后端模板：models.py.tpl, forms.py.tpl, services.py.tpl 等
+   +-- 前端模板：index.vue.tpl, edit.vue.tpl, api.ts.tpl 等
+   |
+   v
+4. 写入文件
+   +-- application/<module>/  # 后端模块
+   +-- ui/src/views/...       # 前端页面
+   +-- ui/src/api/...         # API模块
+   |
+   v
+5. 自动注册
+   +-- 执行 makemigrations/migrate
+   +-- 插入菜单和权限节点
+   +-- 追加路由到 application/urls.py
+   +-- 追加应用到 INSTALLED_APPS
+```
+
+### 4.3.4 配置文件格式
+
+```json
+{
+    "appName": "example",
+    "tableName": "django_example",
+    "tableComment": "案例表",
+    "className": "Example",
+    " moduleName": "案例",
+    "fields": [
+        {
+            "fieldName": "name",
+            "fieldType": "CharField",
+            "fieldComment": "案例名称",
+            "maxLength": 100,
+            "isRequired": true,
+            "isSearch": true,
+            "componentType": "input"
+        },
+        {
+            "fieldName": "status",
+            "fieldType": "IntegerField",
+            "fieldComment": "案例状态",
+            "choices": [
+                {"value": 1, "label": "正常"},
+                {"value": 2, "label": "禁用"}
+            ],
+            "componentType": "select"
+        }
+    ]
+}
+```
+
+## 4.4 模板定制
+
+### 4.4.1 模板目录
+
+代码生成器使用 Jinja2 模板，模板文件位于 `public/templates/` 目录：
+
+```
+public/templates/
+    +-- models.py.tpl         # 模型模板
+    +-- forms.py.tpl          # 表单模板
+    +-- services.py.tpl       # 服务模板
+    +-- views.py.tpl          # 视图模板
+    +-- urls.py.tpl           # 路由模板
+    +-- apps.py.tpl           # 应用配置模板
+    +-- admin.py.tpl          # Admin注册模板
+    +-- migration.py.tpl      # 迁移文件模板
+    +-- ui/
+        +-- index.vue.tpl     # 列表页模板
+        +-- edit.vue.tpl      # 编辑页模板
+        +-- detail.vue.tpl    # 详情页模板
+        +-- api.ts.tpl        # API模块模板
+        +-- columns.ts.tpl    # 表格列配置模板
+        +-- querySchemas.ts.tpl  # 查询表单配置模板
+```
+
+### 4.4.2 模板语法示例
+
+```jinja2
+{# models.py.tpl #}
+from django.db import models
+from application.models import BaseModel
+from utils.common import get_table_name
+
+class {{ className }}(BaseModel):
+    """{{ tableComment }}"""
+{% for field in fields %}
+    {{ field.fieldName }} = models.{{ field.fieldType }}(
+{% if field.maxLength %}        max_length={{ field.maxLength }},{% endif %}
+{% if not field.isRequired %}        null=True, blank=True,{% endif %}
+        verbose_name="{{ field.fieldComment }}",
+        db_comment='{{ field.fieldComment }}'
+    )
+{% endfor %}
+
+    class Meta:
+        db_table = get_table_name('{{ appName }}')
+        db_table_comment = "{{ tableComment }}"
+```
+
+### 4.4.3 自定义模板
+
+开发者可以根据项目需求定制模板：
+
+1. 修改 `public/templates/` 目录下的模板文件
+2. 使用 Jinja2 语法添加自定义逻辑
+3. 重新运行代码生成器应用新的模板
+
+## 4.5 中间件扩展
+
+### 4.5.1 自定义中间件
+
+通过 Django 中间件机制可灵活添加请求/响应处理逻辑：
+
+```python
+# middleware/custom_middleware.py
+class CustomMiddleware:
+    """自定义中间件"""
+
+    def __init__(self, get_response):
+        self.get_response = get_response
+
+    def __call__(self, request):
+        # 请求处理前的逻辑
+        # ...
+
+        response = self.get_response(request)
+
+        # 响应处理后的逻辑
+        # ...
+
+        return response
+```
+
+### 4.5.2 注册中间件
+
+在 `application/settings.py` 中注册自定义中间件：
+
+```python
+MIDDLEWARE = [
+    'corsheaders.middleware.CorsMiddleware',
+    'middleware.custom_middleware.CustomMiddleware',  # 注册自定义中间件
+    # ... 其他中间件
+]
+```
+
+## 4.6 信号机制扩展
+
+### 4.6.1 Django 信号
+
+Django 提供信号机制，可以在特定事件发生时执行自定义逻辑：
+
+```python
+from django.db.models.signals import post_save
+from django.dispatch import receiver
+
+@receiver(post_save, sender=Example)
+def example_post_save(sender, instance, created, **kwargs):
+    """案例保存后的处理"""
+    if created:
+        # 新增记录后的逻辑
+        pass
+    else:
+        # 更新记录后的逻辑
+        pass
+```
+
+### 4.6.2 内置信号
+
+| 信号 | 触发时机 | 说明 |
+|------|----------|------|
+| `pre_save` | 保存前 | 数据验证前 |
+| `post_save` | 保存后 | 数据保存后 |
+| `pre_delete` | 删除前 | 删除前检查 |
+| `post_delete` | 删除后 | 清理关联数据 |
+| `class_prepared` | 模型类准备就绪 | 字段顺序重排 |
+
+## 4.7 自定义管理命令
+
+### 4.7.1 创建管理命令
+
+```python
+# application/management/commands/my_command.py
+from django.core.management.base import BaseCommand
+
+class Command(BaseCommand):
+    help = '自定义管理命令说明'
+
+    def add_arguments(self, parser):
+        parser.add_argument('arg1', type=str, help='参数说明')
+
+    def handle(self, *args, **options):
+        arg1 = options['arg1']
+        # 命令逻辑
+        self.stdout.write(self.style.SUCCESS(f'执行成功: {arg1}'))
+```
+
+### 4.7.2 使用管理命令
+
+```bash
+python manage.py my_command value1
+```
+
+### 4.7.3 内置管理命令
+
+```bash
+python manage.py runserver                    # 启动开发服务器
+python manage.py makemigrations <app>         # 生成迁移文件
+python manage.py migrate                      # 执行迁移
+python manage.py createsuperuser              # 创建超级用户
+python manage.py add_full_comments            # 回填数据库字段注释
+```
+
+## 4.8 前端扩展
+
+### 4.8.1 动态路由
+
+前端路由由后端菜单数据动态生成，新页面通过插入菜单记录自动注册：
+
+```sql
+INSERT INTO django_menu (name, path, component, permission, type, status)
+VALUES ('案例管理', '/example', 'tool/example/index', 'sys:example:page', 0, 0);
+```
+
+### 4.8.2 组件扩展
+
+前端使用 Vue3 + ElementPlus，可通过以下方式扩展：
+
+1. **自定义组件**：在 `ui/src/components/` 目录下创建新组件
+2. **组合式函数**：在 `ui/src/hooks/` 目录下创建自定义 hooks
+3. **全局指令**：在 `ui/src/directives/` 目录下创建自定义指令
+
+### 4.8.3 API 扩展
+
+新增 API 接口需要在 `ui/src/api/` 目录下创建对应的 TypeScript 模块：
+
+```typescript
+// ui/src/api/tool/example.ts
+import { http } from '@/utils/http/axios'
+
+export function getExamplePage(params) {
+    return http.get('/example/page', params)
+}
+
+export function addExample(data) {
+    return http.post('/example/add', data)
+}
+```
+
+## 4.9 扩展性最佳实践
+
+### 新增模块流程
+
+1. **设计数据库表**：确定字段和关联关系
+2. **使用代码生成器**：`python generator.py django_<table>`
+3. **调整生成代码**：根据业务需求修改 Service 层逻辑
+4. **注册菜单权限**：通过管理后台或直接操作数据库
+5. **前端页面定制**：调整 Vue 页面的表格列和表单字段
+
+### 扩展注意事项
+
+1. **遵循规范**：保持与现有模块一致的代码风格
+2. **软删除**：所有查询都要过滤 `is_delete=False`
+3. **权限节点**：为每个操作定义 `sys:<module>:<action>` 权限
+4. **响应格式**：统一使用 `R.ok()` 和 `R.failed()` 返回响应
+5. **操作日志**：使用 `@operation_log` 装饰器记录操作日志