|
|
# {{ project_name }}
|
|
|
|
|
|
FastAPI 业务后端项目。
|
|
|
由 iTi-Flask Copier 模板生成。
|
|
|
|
|
|
AI 修改本项目时优先读：
|
|
|
|
|
|
```text
|
|
|
.codex/skills/{{ project_slug | lower | replace('_', '-') }}-project/SKILL.md
|
|
|
```
|
|
|
|
|
|
该 skill 只描述本项目的通用工程规则。
|
|
|
具体业务知识写在本项目自己的 README/docs。
|
|
|
|
|
|
## 依赖
|
|
|
|
|
|
默认使用私有 Git 依赖。
|
|
|
推荐固定 tag，也允许 branch。
|
|
|
`file://` 只建议框架开发者本机验证模板时使用。
|
|
|
|
|
|
## 初始化
|
|
|
|
|
|
```bash
|
|
|
iticli init
|
|
|
```
|
|
|
|
|
|
`iticli init` 会在 `.env` 不存在时从 `.env.example` 创建。
|
|
|
|
|
|
{% if include_system %}
|
|
|
同步系统 migration 和 seed：
|
|
|
|
|
|
```bash
|
|
|
iticli init system
|
|
|
```
|
|
|
|
|
|
{% endif %}
|
|
|
|
|
|
## 开发
|
|
|
|
|
|
```bash
|
|
|
iticli run dev
|
|
|
iticli test
|
|
|
```
|
|
|
|
|
|
MQ 默认关闭。
|
|
|
使用 Kafka 时先安装带 `mq-kafka` extra 的框架依赖，并在 `.env` 里设置：
|
|
|
|
|
|
```bash
|
|
|
MQ_ENABLED=true
|
|
|
MQ_BACKEND=kafka
|
|
|
KAFKA_BOOTSTRAP_SERVERS=127.0.0.1:9092
|
|
|
KAFKA_GROUP_ID={{ project_slug | lower | replace('-', '_') }}
|
|
|
MQ_CONSUMER_MODE=subscribe
|
|
|
```
|
|
|
|
|
|
如果 Kafka broker 的 consumer group / offset commit 不可用，可切到：
|
|
|
|
|
|
```bash
|
|
|
MQ_CONSUMER_MODE=assign
|
|
|
MQ_OFFSET_STORE_PATH=runtime/mq_offsets.sqlite
|
|
|
```
|
|
|
|
|
|
不同环境把环境名作为 `run` 的第一个参数。
|
|
|
迁移命令使用 `--env` 指定环境：
|
|
|
|
|
|
```bash
|
|
|
iticli run dev
|
|
|
iticli run test 8000
|
|
|
iticli migrate --env prod
|
|
|
```
|
|
|
|
|
|
## Docker
|
|
|
|
|
|
```bash
|
|
|
iticli docker up
|
|
|
iticli docker logs
|
|
|
iticli docker down
|
|
|
```
|
|
|
|
|
|
`iticli docker ...` 会在 `.env` 不存在时从 `.env.example` 创建。
|
|
|
|
|
|
{% if database_dialect == "postgresql" %}
|
|
|
`docker-compose.yml` 默认只启动应用，数据库使用外部 PostgreSQL。
|
|
|
需要本地 PostgreSQL 时使用：
|
|
|
{% else %}
|
|
|
`docker-compose.yml` 默认只启动应用，数据库使用外部 MySQL。
|
|
|
需要本地 MySQL 时使用：
|
|
|
{% endif %}
|
|
|
|
|
|
```bash
|
|
|
iticli docker up --db
|
|
|
iticli docker down --db
|
|
|
```
|
|
|
|
|
|
应用容器启动时会先执行 migration{% if include_system %} 和系统 seed{% endif %}。
|
|
|
本地运行数据写入 `runtime/`，数据库数据写入 Compose volume。
|
|
|
|
|
|
## 同步更新
|
|
|
|
|
|
同步框架包：
|
|
|
|
|
|
```bash
|
|
|
iticli update framework
|
|
|
```
|
|
|
|
|
|
检查模板：
|
|
|
|
|
|
```bash
|
|
|
iticli template check
|
|
|
```
|
|
|
|
|
|
按模板更新项目骨架：
|
|
|
|
|
|
```bash
|
|
|
iticli template update
|
|
|
```
|
|
|
|
|
|
模板更新会改 `main.py`、`app/app_factory.py`、`config.py`、`Dockerfile`、`docker-compose.yml`、`docker-compose.with-db.yml`、`.dockerignore`、`.env.example`、`.vscode/launch.json`、示例模块、测试和项目 skill 等模板拥有的文件。
|
|
|
该命令跟随模板仓库 `HEAD`。
|
|
|
执行前先提交或暂存当前项目改动，执行后检查 diff。
|
|
|
|
|
|
## VSCode 调试
|
|
|
|
|
|
模板内置 `.vscode/launch.json`。
|
|
|
选择 `{{ project_name }}: FastAPI` 即可用 `uvicorn main:app --reload` 调试。
|
|
|
|
|
|
## 数据库迁移
|
|
|
|
|
|
```bash
|
|
|
iticli migrate revision "alice add example table"
|
|
|
iticli migrate
|
|
|
```
|
|
|
|
|
|
规则：
|
|
|
|
|
|
- `migrations/versions` 必须提交。
|
|
|
- migration message 第一个词写作者名。
|
|
|
- 生产只从 `main` 执行 `alembic -c migrations/alembic.ini upgrade head`。
|