iTi-Flask/docs/ARCHITECTURE.md

架构

iTi-Flask 是框架基座。 它提供后端项目的通用工程能力，不内置具体业务。

包定位

框架负责：

• 应用工厂。
• 配置加载。
• APIFlask 集成。
• SQLAlchemy 和 Flask-Migrate 初始化。
• JWT、缓存、限流、日志、错误处理。
• 模块注册协议。
• HTTP JSON 服务客户端。
• 单进程任务运行器。
• Copier 业务项目模板。
• 可选 SPA 静态目录承载。
• 默认 HTML 错误页。

框架不负责：

• 系统业务。
• 业务表和业务路由。
• 业务 seed。
• 业务前端构建产物。

需要系统业务时，业务项目额外依赖 iTi-System。

应用创建流程

create_app() 会按顺序完成这些工作：

1. 解析配置。
2. 创建 APIFlask 应用。
3. 初始化日志、插件、HTTP、JSON、Moment。
4. 初始化数据库、JWT、迁移、限流、缓存、事件总线。
5. 导入业务模型。
6. 初始化服务客户端和任务运行器。
7. 注册模块的 init_app 和 register_commands。
8. 注册可选 SPA 路由。
9. 注册模块路由、权限元数据和菜单元数据。
10. 初始化服务层。

扩展组件

常用扩展从 iti.applications.extensions 引入：

from iti.applications.extensions import db, migrate, jwt, limiter
from iti.applications.extensions import cache_simple, cache_redis, eventbus

框架还提供：

• iti.applications.common.utils.success
• iti.applications.common.utils.fail
• iti.applications.common.utils.page
• iti.applications.common.utils.pagination_builder

后台 API 默认使用响应 envelope：

{"data": {}, "code": 200, "message": "成功"}

服务间 API 应使用真实 HTTP 状态码。

默认错误页

框架内置 403、404、500 HTML 错误页。

请求更偏向 HTML 时返回模板页。 请求更偏向 JSON 时返回：

{"data": null, "code": 404, "message": "Not Found"}

SPA 静态目录

SPA 承载默认关闭。

业务项目开启后，框架从 FRONTEND_PATH 读取 index.html 和静态文件：

FRONTEND_ENABLED = True
FRONTEND_PATH = "frontend/dist"

FRONTEND_PATH 可以是绝对路径。 相对路径按业务项目配置里的 BASE_DIR 解析。

扩展框架

业务项目通过模块扩展框架：

• 注册业务蓝图。
• 注册 CLI 命令。
• 声明权限元数据。
• 声明菜单 seed 元数据。
• 增加业务模型。
• 增加业务配置。
• 配置服务客户端。
• 注册任务。

框架问题在框架仓库修复，再发布新 tag。 业务项目不复制框架源码，也不覆盖框架 import path。