快速上手

环境准备

安装 Python 3.11+，使用公开 PyPI 安装工具。在新目录创建虚拟环境：

mkdir yuanboot-workspace
cd yuanboot-workspace
python -m venv .venv
source .venv/bin/activate
python -m pip install yuanbootctl-python==0.2.0
yuanbootctl-python --version

Windows PowerShell 使用 .venv\Scripts\Activate.ps1 激活环境。 命令名为 yuanbootctl-python，也可通过 python -m yuanboot.cli 调用当前 Python 环境中的工具。 默认生成的项目从公开 PyPI 安装框架，版本与生成工具内置的框架版本一致，安装默认模板无需 Git。 升级工具后新生成项目使用新版本，已创建项目保留原固定版本，见版本与安装。

创建项目

yuanbootctl-python new webapi -n orders --framework-version 0.2.0
cd orders
python -m pip install -e '.[dev]'
yuanbootctl-python run --profile dev --reload

访问：

• http://127.0.0.1:8080/docs：接口文档与在线调试。
• http://127.0.0.1:8080/actuator/health/readiness：就绪状态。
• http://127.0.0.1:8080/actuator/prometheus：监控指标。

--reload 用于本地开发，部署时关闭它。Ctrl+C 停止服务并释放宿主管理的资源。

项目结构

orders/
├── orders/
│   ├── main.py          # 创建应用、读取配置
│   ├── startup.py       # 注册服务和路由
│   ├── endpoints.py     # API 接口
│   └── services.py      # 业务服务
├── config.yml           # 基础配置
├── config_dev.yml       # 开发环境
├── config_fat.yml       # 测试环境
├── config_uat.yml       # 验收环境
├── config_pro.yml       # 生产环境
├── README.md            # 项目说明与文档入口
├── spec/
│   ├── yuanboot-python.md
│   ├── components.md
│   └── backend-module-development.md
├── pyproject.toml       # 业务版本、依赖和运行入口
├── Dockerfile
└── docker-compose.yml

main.py 负责组装宿主，startup.py 注册业务服务与接口，业务处理放在 services.py。 以 mvc 模板创建项目时，接口改为 controllers.py，并包含 templates/ 视图目录。

修改配置与端口

修改 config_dev.yml：

greeting:
  message: "Hello from orders"

指定环境和端口：

yuanbootctl-python run --profile fat --port 9000

配置支持 dev / fat / uat / pro，默认 dev。 详细覆盖规则见配置文件与多环境。

启用组件

python -m pip install -e '.[dev,components]'

模板的 use_components() 根据配置启用 MySQL、Redis、服务发现和日志等组件。 连接参数见组件配置与使用。

下一步

阅读基本概念与架构了解宿主、路由和依赖注入； 参考代码展示编写业务接口； 上线时选择 Docker 部署或宿主机部署。

PyCharm 调试与直接运行

模板提供项目根目录 main.py 和 .run/yuanboot.run.xml。 使用项目虚拟环境安装 pip install -e '.[dev]' 后，直接运行或 Debug 根目录 main.py， 也可从项目根目录执行 python -m demo.main（将 demo 替换为业务包名）。 PyCharm 手动配置使用 Module name demo.main，Working directory 选择项目根目录。 包内入口使用绝对导入，业务项目安装后也支持直接运行 demo/main.py。 配置优先读取当前目录的 config.yml，当前目录没有配置时回退到项目根目录。