Beego 服务稳定核心在于三处约定：控制器必须值类型匿名嵌入 web.Controller；路由优先显式注册避免 AutoRouter 隐式风险；中间件按全局→路由→控制器→方法→Finish(逆序) 严格执行。
Beego 项目不是“写完就能跑”，结构松散、配置错位、中间件乱序，上线后准出问题。真正稳定可维护的 Beego 服务，核心不在语法多炫，而在几处关键约定和边界控制。
beego.Controller 嵌入必须是值类型嵌入，不能是指针或组合
很多新手在定义控制器时写成 type UserCtrl struct { *web.Controller } 或 type UserCtrl struct { Ctr web.Controller }，这会导致 AutoRouter 失效、Ctx 为空、Data 不可用——因为 Beego 的反射注册机制只识别直接嵌入 web.Controller 的结构体（且必须是匿名字段）。
- ✅ 正确写法：
type UserController struct { web.Controller } - ❌ 错误写法：
type UserController struct { Ctrl *web.Controller }或type UserController struct { Ctr web.Controller } - 控制器方法参数绑定依赖此嵌入关系；一旦破坏，
c.Ctx.Input.Param(":id")可能 panic，c.Data无法透传到模板 - 文件必须放在
controllers/目录下，包名必须是controllers，否则bee run不扫描
路由注册优先用 beego.Router()，慎用 AutoRouter
AutoRouter 虽方便，但隐式规则多、调试困难、路径冲突难察觉。生产环境建议显式注册，尤其当 URL 含多个参数或需 RESTful 分离时。
-
beego.Router("/user/:id", &controllers.UserController{}, "get:Get;put:Update")比func (c *UserController) Get(id string)自动匹配更可控 - 路径参数名必须与方法参数名完全一致（
:uid→Get(uid string)），大小写敏感，不支持别名映射 - 若用
beego.NSRouter()定义命名空间，注意NSInclude()中的控制器类型必须已导入，否则编译通过但运行时报panic: reflect: Call of nil function - 手动注册时，
beego.BeeApp.Handlers可查当前所有路由，便于排查重复或遗漏
HTTPS 配置必须用绝对路径 + PEM 链完整性校验
本地开发启 HTTPS 却报 crypto/tls: failed to parse key PEM data？90% 是私钥格式或路径问题。Beego v2 不接受密码保护私钥，也不兼容 PKCS#8 格式。
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
立即学习“go语言免费学习笔记（深入）”；
-
HTTPSCertFile必须是完整链 PEM（服务器证书 + 中间 CA），不能只放cert.crt -
HTTPSKeyFile必须以-----BEGIN RSA PRIVATE KEY-----开头（PKCS#1），不是-----BEGIN PRIVATE KEY-----（PKCS#8） - 路径推荐用绝对路径：
"/home/app/cert.pem"，相对路径在bee run下工作目录易变，常导致文件找不到 - Linux/macOS 下确保私钥权限为
600：chmod 600 key.pem，否则 Go TLS 库拒绝加载
中间件执行顺序必须按注册层级+逆序 Finish
中间件不是“写了就生效”，Beego 的执行流有严格层级和方向：全局 → 路由 → 控制器 → 方法 → Finish()（逆序）。错序会导致鉴权跳过、日志漏记、CORS 头被覆盖。
- 全局中间件用
beego.InsertFilter("*", beego.BeforeRouter, authMiddleware) - 路由级中间件要配合
NSRouter或beego.InsertFilter("/api/*", ...)，不能混用BeforeExec和AfterExec类型 -
Finish()方法在控制器里定义，但中间件的Finish()是逆序执行——最后注册的中间件，其Finish()最先执行 - 避免在中间件里调
c.StopServe()后还继续操作c.Ctx，此时上下文已销毁，可能 panic
Beego 的“约定”不是限制，而是把隐性依赖显性化。最易被忽略的是：控制器嵌入方式决定反射行为，路由注册方式决定参数绑定可靠性，而中间件顺序决定了请求生命周期是否可控——这些点不踩坑，比学十个新特性都管用。
