iti-framework
/
iTi-Flask
6
0
Fork 1
Code Issues Pull Requests Packages Projects Releases Wiki Activity

chore: add helper scripts for project commands

Browse Source
main
NoahLan 2 weeks ago
parent 9a71aa8c93
commit 5ef6da5b53
8 changed files with 554 additions and 26 deletions
Show Stats Download Patch File Download Diff File

34
README.md
Unescape Escape View File

@ -27,7 +27,13 @@ iTi-Flask 是 FastAPI 后端框架基座。
框架本地开发： 框架本地开发：
```bash ```bash
uv sync --extra dev ./scripts/iti.sh install
```
Windows：
```bat
scripts\iti.cmd install
``` ```
业务项目依赖： 业务项目依赖：
@ -55,17 +61,33 @@ app = create_app(
运行： 运行：
```bash ```bash
uv run uvicorn app:app --reload ./scripts/iti.sh serve 8000
``` ```
该命令会启动框架最小应用，可用于验证 `/health`、`/ready`。
## 业务项目生成 ## 业务项目生成
```bash ```bash
uvx copier copy ./copier-template ../my-business-app ./scripts/iti.sh make-app ../my-business-app my_business_app
cd ../my-business-app cd ../my-business-app
uv sync --extra dev ./scripts/app.sh init
uv run alembic upgrade head ./scripts/app.sh serve 8000
uv run uvicorn app:app --reload ```
带 `iti-system`：
```bash
./scripts/iti.sh make-system-app ../my-system-app my_system_app
cd ../my-system-app
./scripts/app.sh init-system
```
所有脚本都带中文 help：
```bash
./scripts/iti.sh help
./scripts/app.sh help
``` ```
## 文档 ## 文档

27
copier-template/README.md.jinja
Unescape Escape View File

@ -12,32 +12,41 @@ FastAPI 业务后端项目。
## 初始化 ## 初始化
```bash ```bash
uv sync --extra dev ./scripts/app.sh init
uv run alembic upgrade head ```
Windows：
```bat
scripts\app.cmd init
``` ```
{% if include_system %} {% if include_system %}
同步系统 migration 和 seed： 同步系统 migration 和 seed：
```bash ```bash
uv run iti-system migrations sync --target migrations/versions ./scripts/app.sh init-system
uv run alembic upgrade head ```
uv run iti-system seed system app:app
Windows：
```bat
scripts\app.cmd init-system
``` ```
{% endif %} {% endif %}
## 开发 ## 开发
```bash ```bash
uv run uvicorn app:app --reload ./scripts/app.sh serve 8000
uv run pytest -q ./scripts/app.sh test
``` ```
## 数据库迁移 ## 数据库迁移
```bash ```bash
uv run alembic revision --autogenerate -m "alice add example table" ./scripts/app.sh migration "alice add example table"
uv run alembic upgrade head ./scripts/app.sh migrate
``` ```
规则： 规则：

127
copier-template/scripts/app.cmd.jinja
Unescape Escape View File

@ -0,0 +1,127 @@
@echo off
setlocal enabledelayedexpansion
set "SCRIPT_DIR=%~dp0"
set "ROOT_DIR=%SCRIPT_DIR%.."
pushd "%ROOT_DIR%" >nul
set "COMMAND=%~1"
if "%COMMAND%"=="" set "COMMAND=help"
shift /1
if "%COMMAND%"=="help" goto help
if "%COMMAND%"=="-h" goto help
if "%COMMAND%"=="--help" goto help
if "%COMMAND%"=="install" goto install
if "%COMMAND%"=="test" goto test
if "%COMMAND%"=="serve" goto serve
if "%COMMAND%"=="migrate" goto migrate
if "%COMMAND%"=="migration" goto migration
if "%COMMAND%"=="heads" goto heads
if "%COMMAND%"=="current" goto current
{% if include_system %}if "%COMMAND%"=="system-sync" goto system_sync
if "%COMMAND%"=="system-seed" goto system_seed
if "%COMMAND%"=="init-system" goto init_system
{% endif %}if "%COMMAND%"=="init" goto init
echo 未知命令：%COMMAND% 1>&2
echo. 1>&2
goto help_error
:help
echo {{ project_name }} 项目脚本
echo.
echo 用法：
echo scripts\app.cmd ^<命令^> [参数]
echo.
echo 常用命令：
echo help 显示帮助
echo install 安装开发依赖：uv sync --extra dev
echo test 运行测试：uv run pytest -q
echo serve [端口] 本地启动，默认 8000
echo migrate 执行 Alembic upgrade head
echo migration ^<说明^> 生成 migration，说明建议以作者名开头
echo heads 查看 Alembic heads
echo current 查看当前 Alembic 版本
{% if include_system %}echo system-sync 同步 iti-system migration 到当前项目
echo system-seed 初始化 / 更新系统 seed
echo init-system system-sync + migrate + system-seed
{% endif %}echo init install + migrate{% if include_system %} + system-seed{% endif %}
echo.
echo 示例：
echo scripts\app.cmd install
echo scripts\app.cmd serve 8000
echo scripts\app.cmd migration "alice add order table"
{% if include_system %}echo scripts\app.cmd init-system
{% endif %}popd >nul
exit /b 0
:help_error
call :help
exit /b 2
:install
uv sync --extra dev
goto end
:test
uv run pytest -q
goto end
:serve
set "PORT=%~1"
if "%PORT%"=="" set "PORT=8000"
uv run uvicorn app:app --reload --port "%PORT%"
goto end
:migrate
uv run alembic upgrade head
goto end
:migration
set "MESSAGE=%~1"
if "%MESSAGE%"=="" (
echo 缺少 migration 说明。示例：scripts\app.cmd migration "alice add order table" 1>&2
exit /b 2
)
uv run alembic revision --autogenerate -m "%MESSAGE%"
goto end
:heads
uv run alembic heads
goto end
:current
uv run alembic current
goto end
{% if include_system %}:system_sync
uv run iti-system migrations sync --target migrations/versions
goto end
:system_seed
uv run iti-system seed system app:app
goto end
:init_system
uv run iti-system migrations sync --target migrations/versions
if errorlevel 1 goto end
uv run alembic upgrade head
if errorlevel 1 goto end
uv run iti-system seed system app:app
goto end
{% endif %}:init
uv sync --extra dev
if errorlevel 1 goto end
{% if include_system %}uv run iti-system migrations sync --target migrations/versions
if errorlevel 1 goto end
{% endif %}uv run alembic upgrade head
if errorlevel 1 goto end
{% if include_system %}uv run iti-system seed system app:app
{% endif %}goto end
:end
set "EXIT_CODE=%ERRORLEVEL%"
popd >nul
exit /b %EXIT_CODE%

94
copier-template/scripts/app.sh.jinja
Unescape Escape View File

@ -0,0 +1,94 @@
#!/usr/bin/env sh
set -eu
ROOT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
cd "$ROOT_DIR"
show_help() {
cat <<'EOF'
{{ project_name }} 项目脚本
用法：
./scripts/app.sh <命令> [参数]
常用命令：
help 显示帮助
install 安装开发依赖：uv sync --extra dev
test 运行测试：uv run pytest -q
serve [端口] 本地启动，默认 8000
migrate 执行 Alembic upgrade head
migration <说明> 生成 migration，说明建议以作者名开头
heads 查看 Alembic heads
current 查看当前 Alembic 版本
{% if include_system %} system-sync 同步 iti-system migration 到当前项目
system-seed 初始化 / 更新系统 seed
init-system system-sync + migrate + system-seed
{% endif %} init install + migrate{% if include_system %} + system-seed{% endif %}
示例：
./scripts/app.sh install
./scripts/app.sh serve 8000
./scripts/app.sh migration "alice add order table"
{% if include_system %} ./scripts/app.sh init-system
{% endif %}
EOF
}
command=${1:-help}
shift || true
case "$command" in
help|-h|--help)
show_help
;;
install)
uv sync --extra dev
;;
test)
uv run pytest -q
;;
serve)
port=${1:-8000}
uv run uvicorn app:app --reload --port "$port"
;;
migrate)
uv run alembic upgrade head
;;
migration)
message=${1:-}
if [ -z "$message" ]; then
echo "缺少 migration 说明。示例：./scripts/app.sh migration \"alice add order table\"" >&2
exit 2
fi
uv run alembic revision --autogenerate -m "$message"
;;
heads)
uv run alembic heads
;;
current)
uv run alembic current
;;
{% if include_system %} system-sync)
uv run iti-system migrations sync --target migrations/versions
;;
system-seed)
uv run iti-system seed system app:app
;;
init-system)
uv run iti-system migrations sync --target migrations/versions
uv run alembic upgrade head
uv run iti-system seed system app:app
;;
{% endif %} init)
uv sync --extra dev
{% if include_system %} uv run iti-system migrations sync --target migrations/versions
{% endif %} uv run alembic upgrade head
{% if include_system %} uv run iti-system seed system app:app
{% endif %} ;;
*)
echo "未知命令：$command" >&2
echo >&2
show_help >&2
exit 2
;;
esac

54
docs/COPIER_TEMPLATE.md
Unescape Escape View File

@ -6,11 +6,19 @@
## 生成 ## 生成
```bash ```bash
uvx copier copy ./copier-template ../my-business-app ./scripts/iti.sh make-app ../my-business-app my_business_app
cd ../my-business-app cd ../my-business-app
uv sync --extra dev ./scripts/app.sh init
uv run alembic upgrade head ./scripts/app.sh serve 8000
uv run uvicorn app:app --reload ```
Windows：
```bat
scripts\iti.cmd make-app ..\my-business-app my_business_app
cd ..\my-business-app
scripts\app.cmd init
scripts\app.cmd serve 8000
``` ```
## 参数 ## 参数
@ -37,6 +45,8 @@ uv run uvicorn app:app --reload
- 示例 FastAPI 模块 - 示例 FastAPI 模块
- 示例 SQLAlchemy 模型 - 示例 SQLAlchemy 模型
- 示例测试 - 示例测试
- `scripts/app.sh`
- `scripts/app.cmd`
## 系统业务 ## 系统业务
@ -44,7 +54,37 @@ uv run uvicorn app:app --reload
生成后执行： 生成后执行：
```bash ```bash
uv run iti-system migrations sync --target migrations/versions ./scripts/app.sh init-system
uv run alembic upgrade head ```
uv run iti-system seed system app:app
Windows：
```bat
scripts\app.cmd init-system
```
## 生成项目脚本
模板会生成两份脚本：
- `scripts/app.sh`：Linux / macOS / Git Bash。
- `scripts/app.cmd`：Windows CMD。
常用命令：
```bash
./scripts/app.sh help
./scripts/app.sh install
./scripts/app.sh test
./scripts/app.sh serve 8000
./scripts/app.sh migration "alice add order table"
./scripts/app.sh migrate
```
带 `iti-system` 的项目还会有：
```bash
./scripts/app.sh system-sync
./scripts/app.sh system-seed
./scripts/app.sh init-system
``` ```

12
docs/README.md
Unescape Escape View File

@ -17,13 +17,17 @@ iTi-Flask 文档只描述框架自身。
## 常用命令 ## 常用命令
```bash ```bash
uv sync --extra dev ./scripts/iti.sh help
uv run --extra dev pytest ./scripts/iti.sh install
uv run --extra dev mypy ./scripts/iti.sh test
./scripts/iti.sh check
``` ```
生成业务项目： 生成业务项目：
```bash ```bash
uvx copier copy ./copier-template ../my-business-app ./scripts/iti.sh make-app ../my-business-app my_business_app
./scripts/iti.sh make-system-app ../my-system-app my_system_app
``` ```
Windows 使用 `scripts\iti.cmd`。

129
scripts/iti.cmd
Unescape Escape View File

@ -0,0 +1,129 @@
@echo off
setlocal enabledelayedexpansion
set "SCRIPT_DIR=%~dp0"
set "ROOT_DIR=%SCRIPT_DIR%.."
pushd "%ROOT_DIR%" >nul
set "COMMAND=%~1"
if "%COMMAND%"=="" set "COMMAND=help"
shift /1
if "%COMMAND%"=="help" goto help
if "%COMMAND%"=="-h" goto help
if "%COMMAND%"=="--help" goto help
if "%COMMAND%"=="install" goto install
if "%COMMAND%"=="test" goto test
if "%COMMAND%"=="check" goto check
if "%COMMAND%"=="serve" goto serve
if "%COMMAND%"=="migrate" goto migrate
if "%COMMAND%"=="migration" goto migration
if "%COMMAND%"=="heads" goto heads
if "%COMMAND%"=="current" goto current
if "%COMMAND%"=="make-app" goto make_app
if "%COMMAND%"=="make-system-app" goto make_system_app
echo 未知命令：%COMMAND% 1>&2
echo. 1>&2
goto help_error
:help
echo iTi-Flask 开发脚本
echo.
echo 用法：
echo scripts\iti.cmd ^<命令^> [参数]
echo.
echo 常用命令：
echo help 显示帮助
echo install 安装开发依赖：uv sync --extra dev
echo test 运行测试：uv run pytest -q
echo check 运行测试和 mypy
echo serve [端口] 启动框架示例应用，默认 8000
echo migrate 执行当前仓库 Alembic upgrade head
echo migration ^<说明^> 生成 migration，说明建议以作者名开头
echo heads 查看 Alembic heads
echo current 查看当前 Alembic 版本
echo make-app ^<目录^> [包名] 从 copier-template 生成业务项目
echo make-system-app ^<目录^> [包名] 生成带 iti-system 的业务项目
echo.
echo 示例：
echo scripts\iti.cmd install
echo scripts\iti.cmd test
echo scripts\iti.cmd serve 8000
echo scripts\iti.cmd make-app ..\hsyh-erp hsyh_erp
echo scripts\iti.cmd make-system-app ..\hsyh-mes-phase2 hsyh_mes_phase2
popd >nul
exit /b 0
:help_error
call :help
exit /b 2
:install
uv sync --extra dev
goto end
:test
uv run pytest -q
goto end
:check
uv run pytest -q
if errorlevel 1 goto end
uv run mypy
goto end
:serve
set "PORT=%~1"
if "%PORT%"=="" set "PORT=8000"
uv run uvicorn iti.app:create_app --factory --reload --port "%PORT%"
goto end
:migrate
uv run alembic upgrade head
goto end
:migration
set "MESSAGE=%~1"
if "%MESSAGE%"=="" (
echo 缺少 migration 说明。示例：scripts\iti.cmd migration "alice add order table" 1>&2
exit /b 2
)
uv run alembic revision --autogenerate -m "%MESSAGE%"
goto end
:heads
uv run alembic heads
goto end
:current
uv run alembic current
goto end
:make_app
set "INCLUDE_SYSTEM=false"
goto make_project
:make_system_app
set "INCLUDE_SYSTEM=true"
goto make_project
:make_project
set "TARGET=%~1"
set "PACKAGE=%~2"
if "%TARGET%"=="" (
echo 缺少目标目录。示例：scripts\iti.cmd make-app ..\my-app my_app 1>&2
exit /b 2
)
if "%PACKAGE%"=="" (
for %%I in ("%TARGET%") do set "PACKAGE=%%~nxI"
set "PACKAGE=!PACKAGE:-=_!"
)
for %%I in ("%TARGET%") do set "PROJECT_NAME=%%~nxI"
uvx copier copy "%CD%\copier-template" "%TARGET%" -d project_name="!PROJECT_NAME!" -d project_slug="!PACKAGE!" -d include_system="%INCLUDE_SYSTEM%"
goto end
:end
set "EXIT_CODE=%ERRORLEVEL%"
popd >nul
exit /b %EXIT_CODE%

103
scripts/iti.sh
Unescape Escape View File

@ -0,0 +1,103 @@
#!/usr/bin/env sh
set -eu
ROOT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
cd "$ROOT_DIR"
show_help() {
cat <<'EOF'
iTi-Flask 开发脚本
用法：
./scripts/iti.sh <命令> [参数]
常用命令：
help 显示帮助
install 安装开发依赖：uv sync --extra dev
test 运行测试：uv run pytest -q
check 运行测试和 mypy
serve [端口] 启动框架示例应用，默认 8000
migrate 执行当前仓库 Alembic upgrade head
migration <说明> 生成 migration，说明建议以作者名开头
heads 查看 Alembic heads
current 查看当前 Alembic 版本
make-app <目录> [包名] 从 copier-template 生成业务项目
make-system-app <目录> [包名] 生成带 iti-system 的业务项目
示例：
./scripts/iti.sh install
./scripts/iti.sh test
./scripts/iti.sh serve 8000
./scripts/iti.sh make-app ../hsyh-erp hsyh_erp
./scripts/iti.sh make-system-app ../hsyh-mes-phase2 hsyh_mes_phase2
说明：
- 默认生成项目使用 copier-template 里的 Git 依赖配置。
- 临时本地验证可在生成时按 copier 交互改成 file://。
EOF
}
command=${1:-help}
shift || true
case "$command" in
help|-h|--help)
show_help
;;
install)
uv sync --extra dev
;;
test)
uv run pytest -q
;;
check)
uv run pytest -q
uv run mypy
;;
serve)
port=${1:-8000}
uv run uvicorn iti.app:create_app --factory --reload --port "$port"
;;
migrate)
uv run alembic upgrade head
;;
migration)
message=${1:-}
if [ -z "$message" ]; then
echo "缺少 migration 说明。示例：./scripts/iti.sh migration \"alice add order table\"" >&2
exit 2
fi
uv run alembic revision --autogenerate -m "$message"
;;
heads)
uv run alembic heads
;;
current)
uv run alembic current
;;
make-app|make-system-app)
target=${1:-}
package=${2:-}
if [ -z "$target" ]; then
echo "缺少目标目录。示例：./scripts/iti.sh make-app ../my-app my_app" >&2
exit 2
fi
if [ -z "$package" ]; then
package=$(basename "$target" | tr '-' '_')
fi
include_system=false
if [ "$command" = "make-system-app" ]; then
include_system=true
fi
uvx copier copy "$ROOT_DIR/copier-template" "$target" \
-d project_name="$(basename "$target")" \
-d project_slug="$package" \
-d include_system="$include_system"
;;
*)
echo "未知命令：$command" >&2
echo >&2
show_help >&2
exit 2
;;
esac
Write Preview
Loading…
Cancel
Save