light-backend-coding

# 后端代码编写与审查 ## 写代码前 读现有代码，匹配项目的风格、约定与依赖库，不擅自引入新框架(CONVENTIONS)。明确输入输出、边界条件、复现要求(种子/版本)。 ## 代码质量标准 - **逻辑清晰**：单一职责、小函数、清楚的数据流。 - **安全**：参数化查询、输入校验、异常处理；不硬编码密钥(走环境变量/配置)；不回显敏感值(a10)。 - **可读**：命名达意、注释解释"为什么"而非"是什么"、与周围代码同密度。 - **可维护/可扩展**：低耦合、配置化(Hydra)、避免过度工程。 - **可复现**：固定随机种子、锁依赖版本、记录环境、确定性数据划分。 ## 工程实践 - **版本控制**：Git；功能分支不直接推 main；有意义的提交信息；仅用户明确要求才提交/推送。 - **依赖/环境**： - uv（推荐，Rust 实现快 10-100x）：`uv init` → `uv add <pkg>` → `uv lock`/`uv sync`(按 `uv.lock` 精确复现) → `uv run`；`uv python pin 3.11` 锁 Python 版本。 - Poetry：`poetry add` → `poetry install`(按 `poetry.lock`)；依赖放 PEP 621 `[project.dependencies]`，dev 依赖入 `[tool.poetry.group.dev]`；CI 固定 Poetry 版本。 - 始终提交 lock 文件，CI 用 `uv sync`/`poetry install` 还原确定性环境。 - **测试**：pytest——文件 `test_*.py`、函数 `test_*` 自动发现，纯 `assert`；`@pytest.fixture`(scope function/module/session) 做依赖注入，`@pytest.mark.parametrize` 跑多组输入，共享 fixture 放 `conftest.py`。新功能/修 bug 先配测试，改完跑 `pytest -x` 验证。覆盖率 `pytest --cov=pkg --cov-report=term-missing`，CI 出 `--cov-report=xml`。 - **质量门**： - Ruff：`[tool.ruff.lint]` 用 `select`/`extend-select`(如加 `B`)/`ignore`(如 `E501`)；`[tool.ruff]` 设 `line-length`/`target-version`；CI 分别跑 `ruff check .` 与 `ruff format --check .`(linter 与 formatter 是两个命令)。 - pre-commit：`.pre-commit-config.yaml` 的 `repos` 用 `rev` 锁版本(tag/SHA，勿用浮动分支)；接 `astral-sh/ruff-pre-commit` 的 `ruff`(`args:[--fix]`)+`ruff-format`；`pre-commit install` 启用，CI 跑 `pre-commit run --all-files`。 - SonarQube(必要时)：`sonar-project.properties` 设 `sonar.sources`/`sonar.tests...