# pyHexScaffold
[](https://badge.fury.io/py/pyHexScaffold)
一个高效的六边形架构（端口和适配器模式）项目脚手架生成器，帮助你快速启动符合最佳实践的Python项目。
## 特性
- 🏗️ 生成符合六边形架构的项目结构
- 🚀 集成FastAPI框架支持
- 💉 内置依赖注入（使用dependency-injector）
- 🔧 完整的环境变量配置系统
- 🐳 Docker容器化支持
- 🛠️ Makefile构建工具支持
- 🧪 单元测试框架配置（pytest）
- 📚 详细的项目文档
- 🔧 gRPC支持
## 安装
使用pip安装pyHexScaffold：
```bash
pip install pyHexScaffold
```
或者从源码安装：
```bash
# 克隆项目
# git clone https://github.com/yourusername/pyHexScaffold.git
# cd pyHexScaffold
# 安装开发版本
pip install -e .
```
## 使用方法
安装完成后，可以通过命令行工具`pyhexscaffold`来生成新的项目：
```bash
# 基本用法
pyhexscaffold /path/to/project
# 自定义项目名称和版本
pyhexscaffold /path/to/project --name my_project --version 0.1.0
# 或者使用简写
pyhexscaffold /path/to/project -n my_project -v 0.1.0
```
### 命令行参数
- `project_path`: 项目路径（必需）
- `--name, -n`: 项目名称（默认：my_hexagonal_app）
- `--version, -v`: 项目版本（默认：1.0.0）
## 生成的项目结构
生成的项目采用六边形架构（端口和适配器模式）设计，清晰地分离了核心业务逻辑与外部依赖：
```
project_name/
├── src/
│ ├── adapters/ # 适配器层 - 与外部系统交互
│ │ ├── api/ # API接口适配器
│ │ ├── dtos/ # 数据传输对象
│ │ ├── events/ # 事件处理适配器
│ │ ├── grpc/ # gRPC适配器
│ │ └── repository/ # 数据存储适配器
│ ├── application/ # 应用层 - 协调领域对象和用例
│ ├── config/ # 配置模块
│ ├── domain/ # 领域层 - 核心业务逻辑和实体
│ ├── ports/ # 端口层 - 定义接口抽象
│ ├── proto/ # Protocol Buffers定义
│ ├── containers.py # 依赖注入容器
│ ├── main.py # 应用入口点
│ └── __init__.py
├── tests/ # 测试目录
│ ├── adapters/ # 适配器层测试
│ ├── application/ # 应用层测试
│ └── conftest.py # 测试配置
├── scripts/ # 辅助脚本
├── docs/ # 项目文档
├── requirements.txt # 项目依赖
├── Dockerfile # Docker构建文件
├── Makefile # 构建工具配置
├── .env # 环境变量配置
├── .gitignore # Git忽略文件
├── .dockerignore # Docker忽略文件
└── README.md # 项目说明文档
```
## 六边形架构概述
六边形架构（也称为端口和适配器模式）的核心思想是将应用程序的核心业务逻辑与外部系统解耦：
- **领域层**（Domain）：包含业务实体、值对象和领域服务，体现核心业务规则。
- **端口层**（Ports）：定义接口，描述核心领域需要与外部世界交互的方式。
- **应用层**（Application）：协调领域对象和端口，实现用例。
- **适配器层**（Adapters）：实现端口，将外部系统（如数据库、API客户端、UI等）连接到核心业务逻辑。
### 基本开发流程
1. 进入项目目录：`cd /path/to/project`
2. 创建虚拟环境：`make venv`
3. 激活虚拟环境：`source .venv/bin/activate`（Linux/Mac）或 `.venv\Scripts\activate`（Windows）
4. 安装依赖：`make install` 或 `make install-dev`（开发依赖）
5. 运行应用：`make run`
6. 运行测试：`make test`
## 示例
以下是一个基本的使用示例：
```python
# 生成一个名为 my_project 的新项目
pyhexscaffold ./my_project --name my_project
# 进入项目目录
cd my_project
# 创建虚拟环境
make venv
source .venv/bin/activate
# 安装依赖
make install-dev
# 运行应用
make run
```
应用程序将在 http://localhost:8000 启动，API文档可在 http://localhost:8000/docs 查看。
## 许可证
本项目采用MIT许可证 - 详见 [LICENSE](LICENSE) 文件
## 贡献
欢迎贡献代码！请先fork项目，然后提交pull request。
## 问题反馈
如有任何问题或建议，请在 [GitHub Issues](https://github.com/yourusername/pyHexScaffold/issues) 中提交。
Raw data
{
"_id": null,
"home_page": null,
"name": "pyHexScaffold",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "hexagonal, architecture, scaffold, generator, FastAPI",
"author": null,
"author_email": "Ray <ray@rayainfo.cn>",
"download_url": "https://files.pythonhosted.org/packages/b3/0b/7fe9d1a407cc4de9e09a0b7956fc9b51b1af401e05bcca308fc94a7f205e/pyhexscaffold-1.0.5.tar.gz",
"platform": null,
"description": "# pyHexScaffold\n\n[](https://badge.fury.io/py/pyHexScaffold)\n\n\u4e00\u4e2a\u9ad8\u6548\u7684\u516d\u8fb9\u5f62\u67b6\u6784\uff08\u7aef\u53e3\u548c\u9002\u914d\u5668\u6a21\u5f0f\uff09\u9879\u76ee\u811a\u624b\u67b6\u751f\u6210\u5668\uff0c\u5e2e\u52a9\u4f60\u5feb\u901f\u542f\u52a8\u7b26\u5408\u6700\u4f73\u5b9e\u8df5\u7684Python\u9879\u76ee\u3002\n\n## \u7279\u6027\n\n- \ud83c\udfd7\ufe0f \u751f\u6210\u7b26\u5408\u516d\u8fb9\u5f62\u67b6\u6784\u7684\u9879\u76ee\u7ed3\u6784\n- \ud83d\ude80 \u96c6\u6210FastAPI\u6846\u67b6\u652f\u6301\n- \ud83d\udc89 \u5185\u7f6e\u4f9d\u8d56\u6ce8\u5165\uff08\u4f7f\u7528dependency-injector\uff09\n- \ud83d\udd27 \u5b8c\u6574\u7684\u73af\u5883\u53d8\u91cf\u914d\u7f6e\u7cfb\u7edf\n- \ud83d\udc33 Docker\u5bb9\u5668\u5316\u652f\u6301\n- \ud83d\udee0\ufe0f Makefile\u6784\u5efa\u5de5\u5177\u652f\u6301\n- \ud83e\uddea \u5355\u5143\u6d4b\u8bd5\u6846\u67b6\u914d\u7f6e\uff08pytest\uff09\n- \ud83d\udcda \u8be6\u7ec6\u7684\u9879\u76ee\u6587\u6863\n- \ud83d\udd27 gRPC\u652f\u6301\n\n## \u5b89\u88c5\n\n\u4f7f\u7528pip\u5b89\u88c5pyHexScaffold\uff1a\n\n```bash\npip install pyHexScaffold\n```\n\n\u6216\u8005\u4ece\u6e90\u7801\u5b89\u88c5\uff1a\n\n```bash\n# \u514b\u9686\u9879\u76ee\n# git clone https://github.com/yourusername/pyHexScaffold.git\n# cd pyHexScaffold\n\n# \u5b89\u88c5\u5f00\u53d1\u7248\u672c\npip install -e .\n```\n\n## \u4f7f\u7528\u65b9\u6cd5\n\n\u5b89\u88c5\u5b8c\u6210\u540e\uff0c\u53ef\u4ee5\u901a\u8fc7\u547d\u4ee4\u884c\u5de5\u5177`pyhexscaffold`\u6765\u751f\u6210\u65b0\u7684\u9879\u76ee\uff1a\n\n```bash\n# \u57fa\u672c\u7528\u6cd5\npyhexscaffold /path/to/project\n\n# \u81ea\u5b9a\u4e49\u9879\u76ee\u540d\u79f0\u548c\u7248\u672c\npyhexscaffold /path/to/project --name my_project --version 0.1.0\n\n# \u6216\u8005\u4f7f\u7528\u7b80\u5199\npyhexscaffold /path/to/project -n my_project -v 0.1.0\n```\n\n### \u547d\u4ee4\u884c\u53c2\u6570\n\n- `project_path`: \u9879\u76ee\u8def\u5f84\uff08\u5fc5\u9700\uff09\n- `--name, -n`: \u9879\u76ee\u540d\u79f0\uff08\u9ed8\u8ba4\uff1amy_hexagonal_app\uff09\n- `--version, -v`: \u9879\u76ee\u7248\u672c\uff08\u9ed8\u8ba4\uff1a1.0.0\uff09\n\n## \u751f\u6210\u7684\u9879\u76ee\u7ed3\u6784\n\n\u751f\u6210\u7684\u9879\u76ee\u91c7\u7528\u516d\u8fb9\u5f62\u67b6\u6784\uff08\u7aef\u53e3\u548c\u9002\u914d\u5668\u6a21\u5f0f\uff09\u8bbe\u8ba1\uff0c\u6e05\u6670\u5730\u5206\u79bb\u4e86\u6838\u5fc3\u4e1a\u52a1\u903b\u8f91\u4e0e\u5916\u90e8\u4f9d\u8d56\uff1a\n\n```\nproject_name/\n\u251c\u2500\u2500 src/\n\u2502 \u251c\u2500\u2500 adapters/ # \u9002\u914d\u5668\u5c42 - \u4e0e\u5916\u90e8\u7cfb\u7edf\u4ea4\u4e92\n\u2502 \u2502 \u251c\u2500\u2500 api/ # API\u63a5\u53e3\u9002\u914d\u5668\n\u2502 \u2502 \u251c\u2500\u2500 dtos/ # \u6570\u636e\u4f20\u8f93\u5bf9\u8c61\n\u2502 \u2502 \u251c\u2500\u2500 events/ # \u4e8b\u4ef6\u5904\u7406\u9002\u914d\u5668\n\u2502 \u2502 \u251c\u2500\u2500 grpc/ # gRPC\u9002\u914d\u5668\n\u2502 \u2502 \u2514\u2500\u2500 repository/ # \u6570\u636e\u5b58\u50a8\u9002\u914d\u5668\n\u2502 \u251c\u2500\u2500 application/ # \u5e94\u7528\u5c42 - \u534f\u8c03\u9886\u57df\u5bf9\u8c61\u548c\u7528\u4f8b\n\u2502 \u251c\u2500\u2500 config/ # \u914d\u7f6e\u6a21\u5757\n\u2502 \u251c\u2500\u2500 domain/ # \u9886\u57df\u5c42 - \u6838\u5fc3\u4e1a\u52a1\u903b\u8f91\u548c\u5b9e\u4f53\n\u2502 \u251c\u2500\u2500 ports/ # \u7aef\u53e3\u5c42 - \u5b9a\u4e49\u63a5\u53e3\u62bd\u8c61\n\u2502 \u251c\u2500\u2500 proto/ # Protocol Buffers\u5b9a\u4e49\n\u2502 \u251c\u2500\u2500 containers.py # \u4f9d\u8d56\u6ce8\u5165\u5bb9\u5668\n\u2502 \u251c\u2500\u2500 main.py # \u5e94\u7528\u5165\u53e3\u70b9\n\u2502 \u2514\u2500\u2500 __init__.py\n\u251c\u2500\u2500 tests/ # \u6d4b\u8bd5\u76ee\u5f55\n\u2502 \u251c\u2500\u2500 adapters/ # \u9002\u914d\u5668\u5c42\u6d4b\u8bd5\n\u2502 \u251c\u2500\u2500 application/ # \u5e94\u7528\u5c42\u6d4b\u8bd5\n\u2502 \u2514\u2500\u2500 conftest.py # \u6d4b\u8bd5\u914d\u7f6e\n\u251c\u2500\u2500 scripts/ # \u8f85\u52a9\u811a\u672c\n\u251c\u2500\u2500 docs/ # \u9879\u76ee\u6587\u6863\n\u251c\u2500\u2500 requirements.txt # \u9879\u76ee\u4f9d\u8d56\n\u251c\u2500\u2500 Dockerfile # Docker\u6784\u5efa\u6587\u4ef6\n\u251c\u2500\u2500 Makefile # \u6784\u5efa\u5de5\u5177\u914d\u7f6e\n\u251c\u2500\u2500 .env # \u73af\u5883\u53d8\u91cf\u914d\u7f6e\n\u251c\u2500\u2500 .gitignore # Git\u5ffd\u7565\u6587\u4ef6\n\u251c\u2500\u2500 .dockerignore # Docker\u5ffd\u7565\u6587\u4ef6\n\u2514\u2500\u2500 README.md # \u9879\u76ee\u8bf4\u660e\u6587\u6863\n```\n\n## \u516d\u8fb9\u5f62\u67b6\u6784\u6982\u8ff0\n\n\u516d\u8fb9\u5f62\u67b6\u6784\uff08\u4e5f\u79f0\u4e3a\u7aef\u53e3\u548c\u9002\u914d\u5668\u6a21\u5f0f\uff09\u7684\u6838\u5fc3\u601d\u60f3\u662f\u5c06\u5e94\u7528\u7a0b\u5e8f\u7684\u6838\u5fc3\u4e1a\u52a1\u903b\u8f91\u4e0e\u5916\u90e8\u7cfb\u7edf\u89e3\u8026\uff1a\n\n- **\u9886\u57df\u5c42**\uff08Domain\uff09\uff1a\u5305\u542b\u4e1a\u52a1\u5b9e\u4f53\u3001\u503c\u5bf9\u8c61\u548c\u9886\u57df\u670d\u52a1\uff0c\u4f53\u73b0\u6838\u5fc3\u4e1a\u52a1\u89c4\u5219\u3002\n- **\u7aef\u53e3\u5c42**\uff08Ports\uff09\uff1a\u5b9a\u4e49\u63a5\u53e3\uff0c\u63cf\u8ff0\u6838\u5fc3\u9886\u57df\u9700\u8981\u4e0e\u5916\u90e8\u4e16\u754c\u4ea4\u4e92\u7684\u65b9\u5f0f\u3002\n- **\u5e94\u7528\u5c42**\uff08Application\uff09\uff1a\u534f\u8c03\u9886\u57df\u5bf9\u8c61\u548c\u7aef\u53e3\uff0c\u5b9e\u73b0\u7528\u4f8b\u3002\n- **\u9002\u914d\u5668\u5c42**\uff08Adapters\uff09\uff1a\u5b9e\u73b0\u7aef\u53e3\uff0c\u5c06\u5916\u90e8\u7cfb\u7edf\uff08\u5982\u6570\u636e\u5e93\u3001API\u5ba2\u6237\u7aef\u3001UI\u7b49\uff09\u8fde\u63a5\u5230\u6838\u5fc3\u4e1a\u52a1\u903b\u8f91\u3002\n\n### \u57fa\u672c\u5f00\u53d1\u6d41\u7a0b\n\n1. \u8fdb\u5165\u9879\u76ee\u76ee\u5f55\uff1a`cd /path/to/project`\n2. \u521b\u5efa\u865a\u62df\u73af\u5883\uff1a`make venv`\n3. \u6fc0\u6d3b\u865a\u62df\u73af\u5883\uff1a`source .venv/bin/activate`\uff08Linux/Mac\uff09\u6216 `.venv\\Scripts\\activate`\uff08Windows\uff09\n4. \u5b89\u88c5\u4f9d\u8d56\uff1a`make install` \u6216 `make install-dev`\uff08\u5f00\u53d1\u4f9d\u8d56\uff09\n5. \u8fd0\u884c\u5e94\u7528\uff1a`make run`\n6. \u8fd0\u884c\u6d4b\u8bd5\uff1a`make test`\n\n## \u793a\u4f8b\n\n\u4ee5\u4e0b\u662f\u4e00\u4e2a\u57fa\u672c\u7684\u4f7f\u7528\u793a\u4f8b\uff1a\n\n```python\n# \u751f\u6210\u4e00\u4e2a\u540d\u4e3a my_project \u7684\u65b0\u9879\u76ee\npyhexscaffold ./my_project --name my_project\n\n# \u8fdb\u5165\u9879\u76ee\u76ee\u5f55\ncd my_project\n\n# \u521b\u5efa\u865a\u62df\u73af\u5883\nmake venv\n\nsource .venv/bin/activate\n\n# \u5b89\u88c5\u4f9d\u8d56\nmake install-dev\n\n# \u8fd0\u884c\u5e94\u7528\nmake run\n```\n\n\u5e94\u7528\u7a0b\u5e8f\u5c06\u5728 http://localhost:8000 \u542f\u52a8\uff0cAPI\u6587\u6863\u53ef\u5728 http://localhost:8000/docs \u67e5\u770b\u3002\n\n## \u8bb8\u53ef\u8bc1\n\n\u672c\u9879\u76ee\u91c7\u7528MIT\u8bb8\u53ef\u8bc1 - \u8be6\u89c1 [LICENSE](LICENSE) \u6587\u4ef6\n\n## \u8d21\u732e\n\n\u6b22\u8fce\u8d21\u732e\u4ee3\u7801\uff01\u8bf7\u5148fork\u9879\u76ee\uff0c\u7136\u540e\u63d0\u4ea4pull request\u3002\n\n## \u95ee\u9898\u53cd\u9988\n\n\u5982\u6709\u4efb\u4f55\u95ee\u9898\u6216\u5efa\u8bae\uff0c\u8bf7\u5728 [GitHub Issues](https://github.com/yourusername/pyHexScaffold/issues) \u4e2d\u63d0\u4ea4\u3002\n",
"bugtrack_url": null,
"license": null,
"summary": "\u516d\u8fb9\u5f62\u67b6\u6784\u9879\u76ee\u811a\u624b\u67b6\u751f\u6210\u5668",
"version": "1.0.5",
"project_urls": {
"Bug Tracker": "https://github.com/DotNetAge/pyHexScaffold/issues",
"Homepage": "https://github.com/DotNetAge/pyHexScaffold"
},
"split_keywords": [
"hexagonal",
" architecture",
" scaffold",
" generator",
" fastapi"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ed3aaff6b70b31a9aae5acf9dcb531d309e11468dd5e329083da7e5fab0c443a",
"md5": "742c7fac1a567105730e7ddda6a9bcca",
"sha256": "cd85c4a3b8c870bab9e6792b7e20a810e119bb55f804b3a5650bd0206abce6c6"
},
"downloads": -1,
"filename": "pyhexscaffold-1.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "742c7fac1a567105730e7ddda6a9bcca",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 23050,
"upload_time": "2025-08-21T03:32:27",
"upload_time_iso_8601": "2025-08-21T03:32:27.337890Z",
"url": "https://files.pythonhosted.org/packages/ed/3a/aff6b70b31a9aae5acf9dcb531d309e11468dd5e329083da7e5fab0c443a/pyhexscaffold-1.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b30b7fe9d1a407cc4de9e09a0b7956fc9b51b1af401e05bcca308fc94a7f205e",
"md5": "787395ddf6321aaac7025c3d7e4e12ef",
"sha256": "4eafed698a5b4ea168203fed21b00c97ce318164eed179777d3827504300f303"
},
"downloads": -1,
"filename": "pyhexscaffold-1.0.5.tar.gz",
"has_sig": false,
"md5_digest": "787395ddf6321aaac7025c3d7e4e12ef",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 16675,
"upload_time": "2025-08-21T03:32:28",
"upload_time_iso_8601": "2025-08-21T03:32:28.432981Z",
"url": "https://files.pythonhosted.org/packages/b3/0b/7fe9d1a407cc4de9e09a0b7956fc9b51b1af401e05bcca308fc94a7f205e/pyhexscaffold-1.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-21 03:32:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "DotNetAge",
"github_project": "pyHexScaffold",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pyhexscaffold"
}
JSON
