docs: 文档整理
parent
47355a0507
commit
69c845aacd
@ -0,0 +1,138 @@
|
|||||||
|
# 配置
|
||||||
|
|
||||||
|
iTi-Flask 内置 `dev`、`test`、`prod` 三套配置。
|
||||||
|
默认环境是 `dev`。
|
||||||
|
|
||||||
|
## 环境选择
|
||||||
|
|
||||||
|
```bash
|
||||||
|
FLASK_ENV=dev uv run python -m flask --app app.py run --debug
|
||||||
|
```
|
||||||
|
|
||||||
|
`create_app(config_name="test")` 可以直接指定环境。
|
||||||
|
|
||||||
|
业务项目通常传入自己的配置映射：
|
||||||
|
|
||||||
|
```python
|
||||||
|
from iti.config import DevConfig as BaseDevConfig
|
||||||
|
from iti.config import ProdConfig as BaseProdConfig
|
||||||
|
from iti.config import TestConfig as BaseTestConfig
|
||||||
|
|
||||||
|
|
||||||
|
class DevConfig(BaseDevConfig):
|
||||||
|
SQLALCHEMY_DATABASE_URI = "sqlite:///runtime/app_dev.db"
|
||||||
|
|
||||||
|
|
||||||
|
class TestConfig(BaseTestConfig):
|
||||||
|
SQLALCHEMY_DATABASE_URI = "sqlite:///:memory:"
|
||||||
|
|
||||||
|
|
||||||
|
class ProdConfig(BaseProdConfig):
|
||||||
|
pass
|
||||||
|
|
||||||
|
|
||||||
|
config = {
|
||||||
|
"dev": DevConfig,
|
||||||
|
"test": TestConfig,
|
||||||
|
"prod": ProdConfig,
|
||||||
|
"default": DevConfig,
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## env 文件
|
||||||
|
|
||||||
|
框架会从当前工作目录加载第一个存在的 env 文件：
|
||||||
|
|
||||||
|
1. `.env.local`
|
||||||
|
2. `.env.<FLASK_ENV>`
|
||||||
|
3. `.env`
|
||||||
|
|
||||||
|
也可以用 `ITI_ENV_DIR` 指定查找目录：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
ITI_ENV_DIR=/path/to/app FLASK_ENV=prod uv run python -m flask --app app.py run
|
||||||
|
```
|
||||||
|
|
||||||
|
## 常用配置项
|
||||||
|
|
||||||
|
| 配置项 | 说明 |
|
||||||
|
| --- | --- |
|
||||||
|
| `SECRET_KEY` | Flask 密钥 |
|
||||||
|
| `JWT_SECRET_KEY` | JWT 密钥 |
|
||||||
|
| `DATABASE_URL` | 数据库连接串 |
|
||||||
|
| `REDIS_URL` | 生产限流存储地址 |
|
||||||
|
| `FRONTEND_ENABLED` | 是否启用 SPA 承载 |
|
||||||
|
| `FRONTEND_PATH` | SPA 构建目录 |
|
||||||
|
| `SERVICES` | 服务客户端配置 |
|
||||||
|
| `TASKS_ENABLED` | 是否启动任务调度线程 |
|
||||||
|
|
||||||
|
## 数据库
|
||||||
|
|
||||||
|
默认使用 SQLite。
|
||||||
|
|
||||||
|
开发环境默认数据库：
|
||||||
|
|
||||||
|
```text
|
||||||
|
runtime/iti-flask_dev.db
|
||||||
|
```
|
||||||
|
|
||||||
|
测试环境使用内存数据库：
|
||||||
|
|
||||||
|
```text
|
||||||
|
sqlite:///:memory:
|
||||||
|
```
|
||||||
|
|
||||||
|
生产环境优先读取 `DATABASE_URL`。
|
||||||
|
`postgres://` 会自动转换为 `postgresql://`。
|
||||||
|
|
||||||
|
## 限流
|
||||||
|
|
||||||
|
默认启用 Flask-Limiter。
|
||||||
|
|
||||||
|
开发环境：
|
||||||
|
|
||||||
|
```python
|
||||||
|
RATELIMIT_ENABLED = True
|
||||||
|
RATELIMIT_STORAGE_URL = "memory://"
|
||||||
|
RATELIMIT_DEFAULT = "1000 per hour"
|
||||||
|
```
|
||||||
|
|
||||||
|
测试环境禁用限流。
|
||||||
|
|
||||||
|
生产环境默认从 `REDIS_URL` 读取存储地址：
|
||||||
|
|
||||||
|
```python
|
||||||
|
RATELIMIT_DEFAULT = "100 per hour"
|
||||||
|
```
|
||||||
|
|
||||||
|
路由级限流：
|
||||||
|
|
||||||
|
```python
|
||||||
|
from iti.applications.extensions import limiter
|
||||||
|
|
||||||
|
|
||||||
|
@bp.get("/reports")
|
||||||
|
@limiter.limit("10 per minute")
|
||||||
|
def list_reports():
|
||||||
|
return {"data": []}
|
||||||
|
```
|
||||||
|
|
||||||
|
## 缓存
|
||||||
|
|
||||||
|
框架初始化两个缓存配置：
|
||||||
|
|
||||||
|
- `CACHE_SIMPLE`
|
||||||
|
- `CACHE_REDIS`
|
||||||
|
|
||||||
|
本地默认启用 `SimpleCache`。
|
||||||
|
Redis 缓存默认关闭。
|
||||||
|
|
||||||
|
## 文件存储
|
||||||
|
|
||||||
|
本地文件默认写入：
|
||||||
|
|
||||||
|
```text
|
||||||
|
runtime/uploads
|
||||||
|
```
|
||||||
|
|
||||||
|
业务项目可以覆盖 `FILE_STORAGE["LOCAL"]["base_path"]`。
|
||||||
@ -0,0 +1,57 @@
|
|||||||
|
# Copier 模板
|
||||||
|
|
||||||
|
`copier-template` 用于生成业务后端项目。
|
||||||
|
模板只生成项目骨架，不复制框架源码。
|
||||||
|
|
||||||
|
## 生成项目
|
||||||
|
|
||||||
|
在 iTi-Flask 仓库根目录执行：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
uvx copier copy ./copier-template ../my-business-app
|
||||||
|
```
|
||||||
|
|
||||||
|
进入生成后的项目：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd ../my-business-app
|
||||||
|
uv sync --extra dev
|
||||||
|
uv run python -m flask --app app.py db upgrade
|
||||||
|
uv run python -m flask --app app.py run --debug
|
||||||
|
```
|
||||||
|
|
||||||
|
## 模板参数
|
||||||
|
|
||||||
|
| 参数 | 说明 |
|
||||||
|
| --- | --- |
|
||||||
|
| `project_name` | 业务项目显示名称 |
|
||||||
|
| `project_slug` | 业务项目 Python 包名 |
|
||||||
|
| `framework_git` | iTi-Flask Git 地址 |
|
||||||
|
| `framework_tag` | iTi-Flask Git tag |
|
||||||
|
| `include_system` | 是否引入 iTi-System |
|
||||||
|
| `system_git` | iTi-System Git 地址 |
|
||||||
|
| `system_tag` | iTi-System Git tag |
|
||||||
|
|
||||||
|
## 生成内容
|
||||||
|
|
||||||
|
模板会生成：
|
||||||
|
|
||||||
|
- `app.py`
|
||||||
|
- `config.py`
|
||||||
|
- `pyproject.toml`
|
||||||
|
- `migrations/`
|
||||||
|
- 业务 Python 包。
|
||||||
|
- 示例模块。
|
||||||
|
- 示例模型。
|
||||||
|
- 示例测试。
|
||||||
|
|
||||||
|
## 扩展方式
|
||||||
|
|
||||||
|
业务项目扩展框架时，只改业务项目自己的文件：
|
||||||
|
|
||||||
|
- 在 `modules/` 下新增业务模块。
|
||||||
|
- 在 `models/` 下新增业务模型。
|
||||||
|
- 在 `config.py` 中覆盖配置。
|
||||||
|
- 在 `app.py` 中注册模块和模型导入函数。
|
||||||
|
|
||||||
|
框架升级通过更新 `pyproject.toml` 中的 Git tag 完成。
|
||||||
@ -1,20 +1,26 @@
|
|||||||
# iTi-Flask 文档
|
# iTi-Flask 文档
|
||||||
|
|
||||||
## 架构与边界
|
iTi-Flask 文档只描述框架自身。
|
||||||
|
|
||||||
- [框架边界](FRAMEWORK_BOUNDARY.md)
|
- [架构](ARCHITECTURE.md)
|
||||||
- [架构重构计划](ARCHITECTURE_REFACTOR_PLAN.md)
|
- [配置](CONFIGURATION.md)
|
||||||
- [模块协议](MODULES.md)
|
- [模块协议](MODULES.md)
|
||||||
- [ERP Service 契约草案](ERP_SERVICE.md)
|
|
||||||
|
|
||||||
## 工程规则
|
|
||||||
|
|
||||||
- [数据库迁移](MIGRATIONS.md)
|
|
||||||
- [种子数据](SEEDS.md)
|
|
||||||
- [服务客户端](SERVICE_CLIENT.md)
|
- [服务客户端](SERVICE_CLIENT.md)
|
||||||
- [任务运行器](TASKS.md)
|
- [任务运行器](TASKS.md)
|
||||||
|
- [数据库迁移](MIGRATIONS.md)
|
||||||
|
- [种子数据](SEEDS.md)
|
||||||
|
- [Copier 模板](COPIER_TEMPLATE.md)
|
||||||
|
|
||||||
|
## 常用命令
|
||||||
|
|
||||||
|
```bash
|
||||||
|
uv sync --extra dev
|
||||||
|
uv run --extra dev pytest
|
||||||
|
uv run --extra dev mypy
|
||||||
|
```
|
||||||
|
|
||||||
## 既有工具文档
|
生成业务项目：
|
||||||
|
|
||||||
- [HTTP 响应工具](HTTP_RESPONSE_UTILS.md)
|
```bash
|
||||||
- [限流配置](LIMITER_CONFIG.md)
|
uvx copier copy ./copier-template ../my-business-app
|
||||||
|
```
|
||||||
|
|||||||
Loading…
Reference in New Issue