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/
快速生成新的模块¶
Hobbit最重要的一个目标就是快速生成可用可测试的项目。自动生成新的业务模块也是提高开发效率中重要的一环。
hobbit gen
命令可根据一个描叙models的csv文件,自动生成models.py、CRUD 的 API、unittest(目前仅支持rivendell模版)。hobbit create
命令可以生成一个csv文件,含有一些基本的例子。
hobbit --echo gen -n user -d /tmp/test -t rivendell --csv-path xx
模版文件说明¶
支持多models,你只需要使用单行定义一次model,紧随其后是model的列定义。
type列和
sqlalchemy.types
对应(除了ref,ref是hobbit-core
定义的外键写法)。有些type需要参数,例如string类型需要一个length,这需要你自己保证定义的正确性。支持测试数据的生成,最后一列test的值即为单元测试需要。
有关 hobbit
的使用,直接查看帮助文档:
hobbit --help
自动补全¶
# 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配置。