Hobbit-core中文文档¶
changelog // github // pypi // issues // API文档 // EN version
基于 Flask + SQLAlchemy + marshmallow + webargs 的 flask 项目生成器。
包含 RESTful API、celery集成、单元测试、gitlab-ci/cd、docker compose 一套解决方案。后续考虑更好的自动文档工具(目前有 apispec )。
为什么我开发了这个项目? 可以参考这一设计范式: Convention over configuration 。
简易教程¶
快速安装¶
pip install "hobbit-core[hobbit,hobbit_core]" # 安装全部功能
pip install "hobbit-core[hobbit,hobbit_core]" --pre # 安装pre release版本
# 仅安装命令依赖,不安装库依赖(安装命令到全局时推荐使用)
pip install "hobbit-core[hobbit]"
快速生成项目¶
使用 hobbit
命令自动生成你的flask项目:
hobbit --echo new -n demo -d . -p 5000 --celery # 建议试用 -t rivendell 新模版
建议使用pipenv创建虚拟环境:
pipenv install -r requirements.txt --pre && pipenv install --dev pytest pytest-cov pytest-env ipython flake8 ipdb
该命令会生成一个完整的api及其测试范例,使用以下项目启动server:
pipenv shell # 使用虚拟环境
FLASK_APP=app/run.py flask run
你可以在控制台看到类似如下信息:
* Serving Flask app "app/run.py"
* Environment: production
WARNING: Do not use the development server in a production environment.
Use a production WSGI server instead.
* Debug mode: off
* Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
访问 http://127.0.0.1:5000/api/ping/
自动补全¶
# bash users add this to your .bashrc
eval "$(_HOBBIT_COMPLETE=source hobbit)"
# zsh users add this to your .zshrc
eval "$(_HOBBIT_COMPLETE=source_zsh hobbit)"
项目结构¶
.
├── Dockerfile
├── app
│ ├── __init__.py
│ ├── configs
│ │ ├── __init__.py
│ │ ├── default.py
│ │ ├── development.py
│ │ ├── production.py
│ │ └── testing.py
│ ├── core
│ │ └── __init__.py
│ ├── exts.py
│ ├── models
│ │ └── __init__.py
│ ├── run.py
│ ├── schemas
│ │ └── __init__.py
│ ├── tasks
│ │ └── __init__.py
│ ├── utils
│ │ └── __init__.py
│ └── views
│ ├── __init__.py
│ └── ping.py
├── configs
│ └── gunicorn-logging.ini
├── deploy.sh
├── docker-compose.yml
├── docs
│ └── index.apib
├── pytest.ini
├── requirements.txt
└── tests
├── __init__.py
├── conftest.py
└── test_ping.py
Dockerfile¶
使用docker来运行我们的web服务,基于同一个docker image运行测试,由此保证开发环境、测试环境、运行时环境一致。你可以在 Dockerfile reference 查看有关Dockerfile的语法。
app¶
app文件夹保存了所有业务层代码。基于 约定优于配置 范式,这个文件夹名字及所有其他文件夹名字 禁止修改 。
configs¶
基于flask设计,我们使用环境变量 FLASK_ENV
加载不同环境的配置文件。例如 FLASK_ENV=production
,会自动加载 configs/production.py
这个文件作为配置文件。
core¶
core文件夹约定编写自定义的基础类库代码,或者临时扩展hobbit_core的基础组件(方便后续直接贡献到hobbit_core)。
exts.py¶
flask项目很容易产生循环引用问题, exts.py
文件的目的就是避免产生这个问题。你可以看下这个解释: Why use exts.py to instance extension?
models¶
所有数据库模型定义在这里。
services¶
使用rivendell模版事会有此模块,类比java结构,这时候约定view不访问model层而去访问sevices层,由sevices层去访问model层。
run.py¶
web项目的入口。你将在这里注册路由、注册命令等等操作。
schemas¶
定义所有的 marshmallow scheams。我们使用marshmallow来序列化api输出,类似 django-rest-framework
的效果。
utils¶
定义所有的公用工具函数。
views¶
路由及简单业务逻辑。
deploy.sh¶
一个简易的部署脚本。配合ci/cd系统一起工作。
docker-compose.yml¶
基本的 docker compose 配置文件。考虑到单机部署需求,自动生成了一个简易的配置,启动项目:
docker-compose up
docs¶
API 文档、model 设计文档、架构设计文档、需求文档等等项目相关的文档。
logs¶
运行时的log文件。
tests¶
所有的测试case. 推荐使用 pytest 测试,项目也会自动生成基本的pytest配置。
配置¶
Key |
Value |
Description |
---|---|---|
HOBBIT_USE_CODE_ORIGIN_TYPE |
True or False |
Return origin type of code in response. Default is False. |
HOBBIT_RESPONSE_MESSAGE_MAPS |
dict, {code: message} |
Self-defined response message. Set to {200: "success"} will return {"code": 200, "message": "success"} in response. |
HOBBIT_RESPONSE_DETAIL |
True or False |
Default return detail and must set to False in production env. Default is True. Only used in 500 server error response. |
Others¶
- Change history
- 2.2.3 (2022-05-18)
- 2.2.2 (2022-02-17)
- 2.2.1 (2021-12-01)
- 2.2.0 (2021-11-18)
- 2.1.1 (2021-10-25)
- 2.0.4 (2021-07-13)
- 2.0.3 (2021-07-08)
- 2.0.2 (2021-07-08)
- 2.0.1 (2021-06-21)
- 2.0.0 (2021-06-20)
- 1.4.4 (2020-03-25)
- 1.4.3 (2019-07-24)
- 1.4.2 (2019-06-13)
- 1.4.1 (2019-05-23)
- 1.4.0 (Obsolete version)
- 1.3.1 (2019-02-26)
- 1.3.0 (2019-01-14)
- 1.2.5 (2018-10-30)
- 1.2.4 (2018-10-18)
- 1.2.3 (2018-10-18)
- 1.2.2 (2018-10-16)
- 1.2.1 (2018-10-12)
- 1.2.0 (2018-10-11)
- 1.1.0 (2018-09-29)
- 1.0.0 (2018-09-25)
- 0.0.[1-9]
- Hobbit-core's API Documentation