代码格式

第一步：手写（src/notes.py）

手写的是这样：单引号、== 两侧没空格，还有一个用不上的 import。

import json

def visible(notes, scope_id):
    return [n for n in notes if n['scope_id']==scope_id]

第二步：ruff format . 之后

跑完排版：引号变双引号，== 两侧补空格，函数前补到两个空行。json 还在——排版工具不管它有没有被用到。

import json

def visible(notes, scope_id):
    return [n for n in notes if n["scope_id"] == scope_id]

第三步：ruff check . 拦住

输出格式与 Makefile 里的 --output-format=concise 一致：文件、行、列、规则号、修法，照着它改。

$ ruff check --output-format=concise .
src/notes.py:1:8: F401 [*] `json` imported but unused
Found 1 error.
[*] 1 fixable with the `--fix` option.

第四步：改完再提交

删掉那一行 import。要保留它，就让代码里真的用到——不许在同一行加 # noqa: F401 了事。scope_id 来自会话这一点从函数体里看不出来，按注释那页的写法补一句文档字符串。

def visible(notes, scope_id):
    """返回属于这个所属范围的笔记。

    scope_id 来自会话，不从请求参数读取。
    """
    return [n for n in notes if n["scope_id"] == scope_id]

助手交出来的样子

$ git diff --stat origin/main
 app/api/notes.py | 247 ++++++++++++++++++++++++++--------------------
 1 file changed, 247 insertions(+), 121 deletions(-)

$ git diff -w --stat origin/main
 app/api/notes.py |   9 +++++----
 1 file changed, 9 insertions(+), 5 deletions(-)

.editorconfig（根目录，管换行与缩进）

花括号、引号这类交给各语言自己的排版工具，这里只管跨语言共有的那几项。C# 的左花括号另起一行也写在这里，由 dotnet format 执行。

root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true

[*.go]
indent_style = tab

[*.{js,jsx,ts,tsx,json,css,yml,yaml,md}]
indent_style = space
indent_size = 2

[*.py]
indent_style = space
indent_size = 4

[*.java]
indent_style = space
indent_size = 2

[*.cs]
indent_style = space
indent_size = 4
csharp_new_line_before_open_brace = all
csharp_new_line_before_else = true
dotnet_sort_system_directives_first = true

[*.rs]
indent_style = space
indent_size = 4

pyproject.toml（Python 的排版与检查规则）

这份 pyproject.toml 是全仓库唯一的一份，与质量门禁指向的是同一份。不要在两处各维护一半，否则改了一处另一处会静默失效。命名（N）与复杂度语句数（PLR）从各自页面用 extend-select 追加。

[tool.ruff]
line-length = 100
indent-width = 4
target-version = "py312"
src = ["scripts", "src"]

[tool.ruff.lint]
select = ["E", "F", "I", "B", "S", "C901"]

[tool.ruff.lint.mccabe]
max-complexity = 10

[tool.ruff.format]
quote-style = "double"
indent-style = "space"

.vscode/settings.json（保存时动作）

扩展 id 以各自扩展页为准。保存时格式化只在装了对应扩展时生效，它不跑 ruff check——F401 只有 make check 拦得住。

{
  "editor.formatOnSave": true,
  "files.eol": "\n",
  "files.insertFinalNewline": true,
  "files.trimTrailingWhitespace": true,
  "[go]": { "editor.defaultFormatter": "golang.go" },
  "[python]": { "editor.defaultFormatter": "charliermarsh.ruff" },
  "[typescript]": { "editor.defaultFormatter": "esbenp.prettier-vscode" }
}

Makefile（本地与持续集成共用一条入口）

某种语言的目录还不存在时，删掉对应行，别留下一条永远失败的命令。make check 的聚合入口在质量门禁里定义，全仓库只有那一处；这一页只加 fmt-check 一个子目标，再把它挂进 check 的依赖里。

.PHONY: fmt fmt-check

fmt:
	ruff format .
	golangci-lint fmt
	npm --prefix frontend run format

# 挂进 check：check: fmt-check lint type secret complexity test
fmt-check:
	ruff format --check .
	npm --prefix frontend run format:check

.github/workflows/check.yml（触发）

工作流只把 make check 搬到服务器上，不在 YAML 里另抄一份规则。

name: check
on:
  pull_request:
  push:
    branches: [main]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
          cache: pip
      - run: pip install -r requirements-dev.txt
      - run: make check