82b1ad2b5c
- api/common/v1 → api/open/v1，路由前缀 /api/common/v1 → /api/open/v1
- 契约层按子功能拆目录：api/open/v1/tools/{uuid,md5,random,time,ip}/index.go
- 控制器同步拆文件：internal/controller/open/{uuid,md5,random,time,ip}.go
- 命名规则（open 优于 common）与 tools 目录规则记入 AGENTS.md
- 冒烟测试：旧路由 404，新路由 5 端点全部通过
2.1 KiB
2.1 KiB
Production layout
service.xpcool.com/
├── api/ # HTTP contracts and Swagger metadata
│ ├── user/v1/ # /api/v1 - client-facing API
│ ├── admin/v1/ # /admin/v1 - administration API
│ └── open/v1/ # /api/open/v1 - open API for frontends (no auth)
│ └── tools/ # one dir per sub-feature: tools/<name>/index.go
├── common/ # public reusable module (no internal/ deps)
│ └── tools/ # utility toolbox: md5, cryptox, uuid, random,
│ # timex, convertx, strx, slicex, ip, filex
├── internal/
│ ├── cmd/ # application bootstrap and route isolation
│ ├── consts/ # application error codes and constants
│ ├── controller/ # API-to-service adapters only (incl. open/ open API)
│ ├── service/ # domain use cases and provider interfaces
│ ├── dao/ # generated by gf gen dao; never hand edited
│ ├── model/
│ │ ├── entity/ # generated database entities
│ │ ├── do/ # generated Data Objects
│ │ ├── dto/ # service boundary input/output
│ │ └── vo/ # API view models
│ ├── middleware/ # configurable route-group middleware
│ └── library/ # JWT, response, pagination primitives
├── docs/change-log/ # per-request change records (agent context)
├── manifest/
│ ├── config/ # config.dev/test/prod.yaml
│ └── sql/ # ordered MySQL migrations
└── utility/ # optional cross-cutting helpers
dao, model/do and model/entity are generated after migration, so their schema never drifts from MySQL. Controllers do not access DAO; only services do.
See AGENTS.md for the agent-facing conventions and the context-memory system.