Flask-Boot 模板项目

# 规范与工具

# 格式规范

格式规范约定开发者以一定的风格进行代码的编写，以增加代码的可读性。比如缩进使用 4 空格代替 tab，文件末尾留空行之类的。

其中最出名的就是 pep8 (opens new window) 规范。

在本模板中使用 yapf (opens new window) 工具对代码进行格式化。

由于 yapf 无法对 pep8 中提到的 import 顺序 (opens new window)进行格式化，模板中又引入 isort (opens new window) 来对 import 进行排序。

模板采用在 pep518 (opens new window) 规范中定义的 pyproject.toml 文件作为整个项目的配置文件。这些格式化工具的众多参数也可以统一放到该文件中，下面是内置的 yapf 和 isort 的配置，供大家参考:

# yapf: Python 代码格式化工具
# https://github.com/google/yapf
# 自定义配置项：https://github.com/google/yapf#knobs
[tool.yapf]
based_on_style = "pep8"
indent_width = 4
column_limit = 120
blank_line_before_nested_class_or_def = true

# isor: Python Import 优化工具
# https://github.com/PyCQA/isort
# 自定义配置项: https://pycqa.github.io/isort/docs/configuration/options.html
[tool.isort]
src_paths = "{{flask-app-name}}"
virtual_env = 'venv' # 默认使用 venv 来查询第三方包
line_length = 120
sections = "FUTURE,STDLIB,THIRDPARTY,FIRSTPARTY,LOCALFOLDER" # import 顺序
no_lines_before = "LOCALFOLDER"

对于虚拟环境不在项目根目录下 venv 的（或者自己建立虚拟环境的），需要在手动修改 isort 中的 virtual_env 这一项，指向正确的环境。

# Lint规范

代码 Linter 是对代码质量（也能检查代码格式）进行检查的工具，一般来说它能发现代码中隐藏的问题，以让代码其在运行时更加的健壮。比如当类型返回为 Optional 时，如果不对类型先进行 None 的检查，Linter 就会告诉我们其中可能存在的风险。

lint

模板原来使用 flake8 (opens new window) 对代码进行检查，现在使用效率更高 ruff (opens new window) 来进行代码检查(ruff完全兼容flake8)。

由于 Lint 的规则 (opens new window) 实在是太多太细，模板中只内置了一些常用的规则，请各个团队按照实际情况进行接入。

下面是模板中内置的规则，供大家参考:

# ruff: Python 代码 Lint 工具
# https://github.com/charliermarsh/ruff
# 自定义配置项： https://beta.ruff.rs/docs/settings/
[tool.ruff]
exclude = [
    ".bzr",
    ".direnv",
    ".eggs",
    ".git",
    ".hg",
    ".mypy_cache",
    ".nox",
    ".pants.d",
    ".ruff_cache",
    ".svn",
    ".tox",
    ".venv",
    "__pypackages__",
    "_build",
    "buck-out",
    "build",
    "dist",
    "node_modules",
    "venv",
]
line-length = 120
select = ["A", "B", "C", "E", "F", "N", "S", "T", "W"] # IGNORE D, I, Q

[tool.ruff.per-file-ignores]
"__init__.py" = ["F401", "E402"]
"migration/*.py" = ["A", "B", "C", "D", "E", "F", "I", "N", "Q", "S", "T", "W"]
"test/*" = ["A", "B", "C", "D", "E", "F", "I", "N", "Q", "S", "T", "W"]

TIP

ruff 还支持对代码进行 fix ，比如可以帮你删除没有使用的 import。

本文档不再赘述

# 类型检查

Python 是动态语言，变量类型对它来说根本不存在。但为了大型项目的可维护，在 pep-484 (opens new window) 等规范后逐渐引入了 TypeHint 和类型检查。

本模板没有集成对代码类型的检查，但一个比较常用的工具是mypy (opens new window)，如果希望使用的话可以自行选择集成。

如果开发者使用 vscode 进行开发，那么安装完 python 插件后就默认使用 mypy 进行类型检查和 typehint，可以在开发的时候注意下 IDE 的提示，尽量确保没有红色的报警。

← 使用方法 →