必须用beego/v2而非v1，因v1已停更、模块强耦合、无法单独升级、日志与配置强绑定、路由性能低30%+且不支持opentelemetry；v2模块化设计（web/logs/orm分离）、分层架构、路径契约化、模型与orm解耦，适配企业级长期演进。
Beego v2 是当前唯一值得在新企业级项目中投入的版本，v1 已停止维护，且模块耦合严重，升级路径断裂。
为什么必须用 beego/v2 而不是 beego/v1
v1 的导入路径是 github.com/astaxie/beego，所有模块（日志、缓存、ORM）打包在一个大包里，导致：
- 无法单独升级 ORM 模块而不影响路由或 session 行为
-
beego.BeeLogger与beego.AppConfig强绑定，替换日志后配置读取可能异常 - 路由性能比 v2 低 30%+，实测高并发下
beego.Router的正则匹配开销明显更高 - 没有
core/logs独立包，日志写入无法对接 OpenTelemetry 或 Loki
v2 的模块化设计（server/web、core/logs、client/orm）让各组件可插拔，适合企业级长期演进。
controllers 目录不能直接放业务逻辑
常见错误是把用户注册、权限校验、参数校验全塞进 ExampleController 的 Post 方法里，结果控制器膨胀到 800+ 行，单元测试无法覆盖。
正确做法是分层剥离：
- 参数校验交给
valid包或自定义binding结构体（用valid:"Required;Min(6)"标签） - 核心业务逻辑下沉到
service/user_service.go，控制器只负责调用userSvc.CreateUser() - 权限检查用中间件（
auth.Middleware），而不是每个Prepare()里重复写if !c.IsLogin() { c.Abort("401") } - 错误统一转成
errors.Join(err, errors.New("failed to create user"))，由全局Recovery中间件捕获并返回结构化响应
models 层必须与 ORM 解耦
直接在 models/user.go 里嵌入 orm.Model 或依赖 orm.QuerySeter，会导致模型无法脱离 Beego 运行（比如 CLI 工具、离线数据迁移脚本）。
推荐结构：
-
models/user.go：纯 Go struct，带json和ormtag，不 import 任何 beego 包 -
client/orm/user_query.go：封装orm.QuerySeter操作，如FindByEmail(email string) (*User, error) -
client/orm/init.go：只在这里 importgithub.com/beego/beego/v2/client/orm并调用orm.RegisterModel(new(User))
这样模型可被其他模块（如 cmd/migrate）复用，也方便未来替换 ORM。
router.go 里别写硬编码路径
写 beego.Router("/api/v1/users", &controllers.UserController{}, "get:List") 看似简单，但当需要加版本前缀、统一鉴权、或迁移到 API 网关时，就得全局搜索替换。
更可持续的做法：
- 用常量定义路径：
const UserListPath = "/api/v1/users"，放在pkg/route/path.go - 路由注册集中到
routers/api_v1.go，用beego.NSRouter分组 - 所有 v1 接口统一挂载中间件：
NS.Filter(&context.HTTPMethodFilter{AllowMethods: "GET,POST,PUT"}) - 避免使用
beego.AutoRouter—— 它依赖函数名推导路径，一旦重命名就断链，CI 无法静态检查
路径不是字符串，是契约；改一次，要确保文档、前端、网关、监控全部同步，所以越早约束越省事。
