|
|
# Copier 模板
|
|
|
|
|
|
当前框架仓库根目录是 Copier 模板源。
|
|
|
`copier.yml` 通过 `_subdirectory: copier-template` 指向实际模板目录。
|
|
|
`copier-template` 生成 FastAPI 业务后端骨架。
|
|
|
模板只引用框架包，不复制框架源码。
|
|
|
模板会为生成项目渲染项目 skill。
|
|
|
生成后的路径是：
|
|
|
|
|
|
```text
|
|
|
.codex/skills/<project-slug>-project/SKILL.md
|
|
|
```
|
|
|
|
|
|
模板源文件是：
|
|
|
|
|
|
```text
|
|
|
copier-template/.codex/skills/{{ project_slug | lower | replace('_', '-') }}-project/SKILL.md.jinja
|
|
|
```
|
|
|
|
|
|
模板结构、脚本命令或模块约定变化时，同步更新该模板 skill。
|
|
|
现有模板生成项目需要按当前项目名刷新自己的 skill。
|
|
|
|
|
|
## 生成
|
|
|
|
|
|
```bash
|
|
|
iticli create ../my-business-app
|
|
|
cd ../my-business-app
|
|
|
cp .env.example .env
|
|
|
iticli init
|
|
|
iticli run dev 8000
|
|
|
```
|
|
|
|
|
|
Windows：
|
|
|
|
|
|
```bat
|
|
|
iticli create ..\my-business-app
|
|
|
cd ..\my-business-app
|
|
|
iticli init
|
|
|
iticli run dev 8000
|
|
|
```
|
|
|
|
|
|
## 参数
|
|
|
|
|
|
| 参数 | 说明 |
|
|
|
| --- | --- |
|
|
|
| `project_name` | 业务项目显示名称 |
|
|
|
| `project_slug` | 业务项目发行包名来源 |
|
|
|
| `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 |
|
|
|
|
|
|
默认推荐私有 Git tag。
|
|
|
允许改成 branch 或 `file://`，但多人协作项目不建议依赖本机路径。
|
|
|
|
|
|
## 生成内容
|
|
|
|
|
|
- `main.py`
|
|
|
- `app/app_factory.py`
|
|
|
- `config.py`
|
|
|
- `pyproject.toml`
|
|
|
- `migrations/`
|
|
|
- `Dockerfile`
|
|
|
- `docker-compose.yml`
|
|
|
- `docker-compose.with-db.yml`
|
|
|
- `.dockerignore`
|
|
|
- `.vscode/launch.json`
|
|
|
- `.env.example`
|
|
|
- 示例 FastAPI 模块
|
|
|
- 示例 SQLAlchemy 模型
|
|
|
- 示例测试
|
|
|
|
|
|
## 系统业务
|
|
|
|
|
|
选择 `include_system=true` 时，模板会注册 `create_system_module()`。
|
|
|
生成后执行：
|
|
|
|
|
|
```bash
|
|
|
iticli init system
|
|
|
```
|
|
|
|
|
|
Windows：
|
|
|
|
|
|
```bat
|
|
|
iticli init system
|
|
|
```
|
|
|
|
|
|
## 命令
|
|
|
|
|
|
常用命令：
|
|
|
|
|
|
```bash
|
|
|
iticli help
|
|
|
iticli install
|
|
|
iticli test
|
|
|
iticli run dev 8000
|
|
|
iticli docker up
|
|
|
iticli docker up --db
|
|
|
iticli docker logs
|
|
|
iticli docker down
|
|
|
iticli docker down --db
|
|
|
iticli migrate revision "alice add order table"
|
|
|
iticli migrate
|
|
|
```
|
|
|
|
|
|
`iticli migrate` 在业务项目内使用项目自己的 `migrations/alembic.ini`。
|
|
|
|
|
|
带 `iti-system` 的项目还会有：
|
|
|
|
|
|
```bash
|
|
|
iticli sync system
|
|
|
iticli init system
|
|
|
```
|
|
|
|
|
|
## 同步更新
|
|
|
|
|
|
业务项目同步框架依赖：
|
|
|
|
|
|
```bash
|
|
|
iticli sync flask
|
|
|
```
|
|
|
|
|
|
该命令执行 `uv sync --upgrade-package iti-flask`。
|
|
|
需要同时升级框架和系统包时使用 `iticli sync all`。
|
|
|
|
|
|
业务项目检查模板版本：
|
|
|
|
|
|
```bash
|
|
|
iticli template check
|
|
|
```
|
|
|
|
|
|
该命令执行 `uvx copier update --defaults --pretend --vcs-ref HEAD`。
|
|
|
|
|
|
业务项目按模板更新项目骨架：
|
|
|
|
|
|
```bash
|
|
|
iticli template update
|
|
|
```
|
|
|
|
|
|
该命令执行 `uvx copier update --defaults --vcs-ref HEAD`。
|
|
|
它依赖 `.copier-answers.yml` 里的 `_src_path` 和 `_commit`。
|
|
|
模板更新前，业务项目工作区必须干净。
|
|
|
执行后检查 diff，再运行测试。
|
|
|
|
|
|
模板拥有的文件包括 `main.py`、`app/app_factory.py`、`config.py`、`Dockerfile`、`docker-compose.yml`、`docker-compose.with-db.yml`、`.dockerignore`、`.env.example`、`.vscode/launch.json`、`pyproject.toml`、`migrations/`、示例模块、示例测试、README 和项目 skill。
|
|
|
业务项目自己的模块、模型、API 文档和业务 README 由业务项目维护。
|
|
|
|
|
|
## Docker
|
|
|
|
|
|
模板生成：
|
|
|
|
|
|
- `Dockerfile`：基于 `python:3.11-slim`，使用 `uv sync --frozen --no-dev` 安装运行依赖。
|
|
|
- `docker-compose.yml`：启动应用，默认连接外部 MySQL。
|
|
|
- `docker-compose.with-db.yml`：叠加启动 MySQL 8.4。
|
|
|
- `.env.example`：Compose 和本地运行共用的环境变量样例。
|
|
|
- `.dockerignore`：排除虚拟环境、运行数据和本地密钥。
|
|
|
|
|
|
应用容器启动时会执行业务 migration。
|
|
|
带 `iti-system` 的项目还会先同步 system migration，并执行 system seed。
|
|
|
|
|
|
## VSCode
|
|
|
|
|
|
模板生成 `.vscode/launch.json`。
|
|
|
默认调试配置以 `uvicorn main:app --reload` 启动，使用 `APP_ENV=dev`。
|