目录结构

顶层结构（服务形态）

api/、configs/、scripts/、deployments/ 不在里面——它们有了文件再建，建的时候同步改下一节检查脚本里的白名单。

.
├── cmd/
│   └── server/
│       └── main.go
├── internal/
│   ├── notes/
│   │   ├── notes.go
│   │   └── notes_test.go
│   ├── store/
│   └── session/
├── frontend/
│   ├── src/
│   │   ├── pages/
│   │   └── api/
│   └── package.json
├── migrations/
├── docs/
│   ├── decisions/
│   └── notes-check.md
├── .editorconfig
├── .env.example
├── Makefile
├── go.mod
└── README.md

一个功能包的完整形态：internal/notes/

测试文件与被测代码同目录，不搬到某个统一的 test/ 下。go test 会就近发现 *_test.go。包名是目录的最后一段。

package notes

type Note struct {
	ID      int64
	Title   string
	ScopeID int64
}

func Visible(list []Note, scopeID int64) []Note {
	out := make([]Note, 0)
	for _, n := range list {
		if n.ScopeID == scopeID {
			out = append(out, n)
		}
	}
	return out
}

internal/notes/notes_test.go

同目录、同包。黑盒测试才用 package notes_test，那是 Go 对测试的约定，不是业务目录的划分方式。

package notes

import "testing"

func TestVisibleKeepsOwnScope(t *testing.T) {
	list := []Note{
		{ID: 1, Title: "a", ScopeID: 10},
		{ID: 2, Title: "b", ScopeID: 20},
	}
	got := Visible(list, 10)
	if len(got) != 1 || got[0].ID != 1 {
		t.Fatalf("got %#v", got)
	}
}

scripts/check-layout.sh

白名单是布局决议的机器可读版本。新增目录时改这个文件，并在 docs/decisions/0035-layout.md 里写一句理由——这样「加目录」和「说明为什么加」就绑在同一次合并请求里。

#!/bin/sh
# 顶层目录白名单。新增目录时改这里，并在 docs/decisions/0035-layout.md 里写明理由。
allowed="cmd internal frontend migrations docs"

status=0
for d in ./*/; do
    name=$(basename "$d")
    case " $allowed " in
        *" $name "*) ;;
        *) echo "未登记的顶层目录: $name"; status=1 ;;
    esac
done
exit $status

Makefile（并进 check）

脚本已经排除隐藏目录（./*/ 不匹配以点开头的名字）。本机装了 node_modules 或 vendor 时把它们加进白名单，否则会误报。make check 的聚合入口只在质量门禁里定义一次，这一页只加子目标。

.PHONY: layout layout-check

layout:
	sh scripts/check-layout.sh

# 挂进 check：check: fmt-check lint type layout-check secret complexity test
layout-check: layout
	ruff check --output-format=concise .

两条人工确认的命令

git 不跟踪空目录，所以这些目录只存在于某个人的本机。跑第一条找出它们，跑第二条列出所有顶层被跟踪文件，核对根目录有没有堆东西。

git status --porcelain --ignored | grep '^!!' | grep '/$'
git ls-files | awk -F/ 'NF==1'

助手交出来的样子

app/
├── utils/
│   ├── helpers.go        ← 什么都往里放
│   └── common.go
├── handlers/             ← 空目录
├── services/             ← 空目录
└── pkg/                  ← 空目录