From 37ecff4fc3aaa33671a8d2f146da263ebcfde88a Mon Sep 17 00:00:00 2001 From: Wu Clan Date: Sun, 11 Jun 2023 12:50:06 +0800 Subject: [PATCH] Update the README document (#113) * Update the README document * fix typo --- README.md | 137 ++++++++++++++++++++++++++++++------------------ README.zh-CN.md | 85 +++++++++++++++++++++--------- 2 files changed, 145 insertions(+), 77 deletions(-) diff --git a/README.md b/README.md index 341e5c4c..0240fb92 100644 --- a/README.md +++ b/README.md @@ -2,49 +2,60 @@ English | [简体中文](./README.zh-CN.md) -This is a basic project of the FastAPI framework, using a pseudo three-tier architecture, **still in production** +This is a base project for the FastAPI framework, using a pseudo three-tier architecture, **still in production**. -It‘s purpose is to allow you to develop your project directly with it as your base project +It is intended to allow you to use it directly as your infrastructure to develop your project, this repository as a +template library public, can be used directly -Support python3.10 and above +Support **python3.10** and above -## Skill +## Pseudo three-tier architecture -- [x] FastAPI -- [x] Pydantic -- [x] SQLAlchemy -- [x] Alembic -- [x] Casbin -- [x] MySQL -- [x] Redis -- [x] APScheduler -- [x] Docker +In python web frameworks, the mvc architecture is the most common, but for restful users, the three-tier architecture is +the way to go -## Clone +But in python development, there is no universal standard for the concept of a three-tier architecture, so here I call +it a pseudo three-tier architecture -```shell -git clone https://github.com/wu-clan/fastapi_best_architecture.git -``` +| workflow | java | fastapi_best_architecture | +|-----------------|----------------|---------------------------| +| view | controller | api / view | +| data validation | dto | schema | +| business logic | service + impl | service | +| data access | dao / mapper | crud | +| model | model / entity | model | -## Use: +## Features -### 1：Tradition +- [x] FastAPI New Features +- [x] Asynchronous design +- [x] RESTful API specification +- [x] SQLAlchemy 2.0 syntax +- [x] Pydantic Data Validation +- [x] Casbin RBAC Permission Control +- [x] APScheduler Timed Tasks +- [x] JWT Authentication +- [x] Redis Caching +- [x] Docker Deployment +- [x] Pytest testing + +## Getting started: + +### 1: Legacy mode 1. Install dependencies + ```shell + pip install -r requirements.txt + ``` - ```shell - pip install -r requirements.txt - ``` - -2. Create a database `fba`, choose utf8mb4 encode +2. Create a database ``fba``, choose utf8mb4 encoding 3. Install and start Redis -4. create a `.env` file in the `backend/app/` directory +4. Create a `.env` file in the `backend/app/` directory - ```shell - cd backend/app/ - - touch .env - ``` + ```shell + cd backend/app/ + touch .env + ``` 5. Copy `.env.example` to `.env` @@ -52,59 +63,70 @@ git clone https://github.com/wu-clan/fastapi_best_architecture.git cp .env.example .env ``` -6. Perform a database migration [alembic](https://alembic.sqlalchemy.org/en/latest/tutorial.html) +6. Database migration [alembic](https://alembic.sqlalchemy.org/en/latest/tutorial.html) ```shell cd backend/app/ - - # Generate the migration file - alembic revision --autogenerate - - # Perform the migration - alembic upgrade head - ``` -7. Execute the `backend/app/main.py` file startup service + # Generate migration file + alembic revision --autogenerate + + # Execute the migration + alembic upgrade head + ``` + +7. Execute the `backend/app/main.py` file to start the service 8. Browser access: http://127.0.0.1:8000/v1/docs --- -### 2：Docker +### 2: Docker -1. Go to the directory where the `docker-compose.yml` file is located and create the environment variable file `.env` +1. Go to the directory where the ``docker-compose.yml`` file is located and create the environment variable + file ``.env`` ```shell - cp .env.server ../../backend/app/.env + cp .env.server ../../backend/app/.env # This command is optional cp .env.docker .env ``` -2. Execute the one-click start command +2. Execute the one-click boot command ```shell docker-compose up -d -build ``` -3. Wait for the command to finish automatically -4. Browser access: http://127.0.0.1:8000/v1/docs +3. Wait for the command to complete automatically +4. Visit the browser: http://127.0.0.1:8000/v1/docs -## Init the test data +## Test data -Execute the `backend/app/init_test_data.py` file +Execute ``backend/app/init_test_data.py`` file to automatically create test data + +## Development + +Development process, for reference only + +1. Define the database model (model) and remember to perform database migration for each change +2. Define the data validation model (schema) +3. Define the business logic (service) +4. Define routes (router) and views (api) +5. Write database operations (crud) ## Test -Perform tests via pytest +Execute tests via pytest -1. Create a database `fba_test`, choose utf8mb4 encode -2. First, go to the app directory +1. Create the test database `fba_test`, select utf8mb4 encoding +2. Enter the app directory ```shell cd backend/app/ ``` -3. Init the test data +3. Initialize the test data ```shell python tests/init_test_data.py @@ -115,3 +137,16 @@ Perform tests via pytest ```shell pytest -vs --disable-warnings ``` + +## Thanks + +- [FastAPI](https://fastapi.tiangolo.com/) +- [Pydantic](https://docs.pydantic.dev/latest/) +- [SQLAlchemy](https://docs.sqlalchemy.org/en/20/) +- [Casbin](https://casbin.org/zh/) +- [Ruff](https://beta.ruff.rs/docs/) +- ...... + +## License + +This project is licensed under the terms of the MIT license diff --git a/README.zh-CN.md b/README.zh-CN.md index d25dbaa5..ef521934 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -4,40 +4,50 @@ 这是 FastAPI 框架的一个基础项目，使用伪三层架构，**目前还在制作中** -它的目的是让你直接用它作为你的基础项目来开发你的项目 +它的目的是让你可以直接用它作为你的基础架构来开发你的项目，本仓库作为模板库公开，可直接使用 -支持 python3.10 及以上版本 +支持 **python3.10** 及以上版本 -## 技术栈 +## 伪三层架构 -- [x] FastAPI -- [x] Pydantic -- [x] SQLAlchemy -- [x] Alembic -- [x] Casbin -- [x] MySQL -- [x] Redis -- [x] APScheduler -- [x] Docker +在 python 的 web 框架中，mvc 架构是最常见的，但是对于 restful 用户，三层架构是不二选择 -## 克隆 +但是在 python 开发中，三层架构的概念并没有通用标准，所以这里我称之为伪三层架构 -```shell -git clone https://github.com/wu-clan/fastapi_best_architecture.git -``` +| 工作流程 | java | fastapi_best_architecture | +|------|----------------|---------------------------| +| 视图 | controller | api / view | +| 数据验证 | dto | schema | +| 业务逻辑 | service + impl | service | +| 数据访问 | dao / mapper | crud | +| 模型 | model / entity | model | -## 使用： +## 特征 -### 1：传统 +- [x] FastAPI 新特性 +- [x] 异步设计 +- [x] RESTful API 规范 +- [x] SQLAlchemy 2.0 语法 +- [x] Pydantic 数据验证 +- [x] Casbin RBAC 权限控制 +- [x] APScheduler 定时任务 +- [x] JWT 认证 +- [x] Redis 缓存 +- [x] Docker 部署 +- [x] Pytest 测试 + +## 开始： + +### 1：传统模式 1. 安装依赖项 ```shell pip install -r requirements.txt ``` -2. 创建一个数据库`fba`，选择 utf8mb4 编码 +2. 创建一个数据库 `fba`，选择 utf8mb4 编码 3. 安装并启动 Redis -4. 在`backend/app/`目录下创建一个`.env`文件 +4. 在 `backend/app/` 目录下创建一个 `.env` 文件 ```shell cd backend/app/ @@ -50,7 +60,7 @@ git clone https://github.com/wu-clan/fastapi_best_architecture.git cp .env.example .env ``` -6. 进行数据库迁移[alembic](https://alembic.sqlalchemy.org/en/latest/tutorial.html) +6. 数据库迁移 [alembic](https://alembic.sqlalchemy.org/en/latest/tutorial.html) ```shell cd backend/app/ @@ -87,16 +97,26 @@ git clone https://github.com/wu-clan/fastapi_best_architecture.git 3. 等待命令自动完成 4. 浏览器访问：http://127.0.0.1:8000/v1/docs -## 初始化测试数据 +## 测试数据 -执行 `backend/app/init_test_data.py` 文件 +执行 `backend/app/init_test_data.py` 文件，自动创建测试数据 + +## 开发 + +开发流程，仅供参考 + +1. 定义数据库模型（model），每次变化记得执行数据库迁移 +2. 定义数据验证模型（schema） +3. 定义业务逻辑（service） +4. 定义路由（router）和视图（api） +5. 编写数据库操作（crud） ## 测试 -通过 pytest 进行测试 +通过 pytest 执行测试 -1. 创建一个数据库`fba_test`，选择 utf8mb4 编码 -2. 首先，进入app目录 +1. 创建测试数据库 `fba_test`，选择 utf8mb4 编码 +2. 进入app目录 ```shell cd backend/app/ @@ -113,3 +133,16 @@ git clone https://github.com/wu-clan/fastapi_best_architecture.git ```shell pytest -vs --disable-warnings ``` + +## 鸣谢 + +- [FastAPI](https://fastapi.tiangolo.com/) +- [Pydantic](https://docs.pydantic.dev/latest/) +- [SQLAlchemy](https://docs.sqlalchemy.org/en/20/) +- [Casbin](https://casbin.org/zh/) +- [Ruff](https://beta.ruff.rs/docs/) +- ...... + +## 许可证 + +本项目根据 MIT 许可证的条款进行许可