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 模版文件说明 ^^^^^^^^^^^^^ 1. 支持多models，你只需要使用单行定义一次model，紧随其后是model的列定义。 2. type列和 ``sqlalchemy.types`` 对应（除了ref，ref是 ``hobbit-core`` 定义的外键写法）。有些type需要参数，例如string类型需要一个length，这需要你自己保证定义的正确性。 3. 支持测试数据的生成，最后一列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配置。 Others ====== .. toctree:: :maxdepth: 2 changelog api