正确初始化 mvc application 需调用 mvc.new(app.party("/api")) 绑定路由分组,按方法名前缀(如 getusers→/users)自动映射路径,模板路径须匹配 registerview 设置,依赖注入需在 handle 前用 register 注册并配合 inject:"" 标签。

直接用 mvc.New + Handle 就能跑通基础 MVC,但目录结构、依赖注入和路由映射规则不按规范来,很快会卡在 controller 找不到方法、模板渲染失败、或参数取不到值上。
如何正确初始化 MVC Application 并挂载到路由组
关键不是「新建 app」,而是把 mvc.Application 绑定到一个 app.Party 路由分组上——否则所有 controller 方法注册的路径都默认落在根路径,容易冲突或 404。
-
mvc.New(app.Party("/api"))比mvc.New(app)更安全,明确限定该 MVC 实例只处理/api下的所有请求 - 不要在
app.Run之后调用mvc.New,Iris 不允许运行时动态注册路由组 - 如果要用子路径(如
/admin/users),必须写成mvc.New(app.Party("/admin/users")),不能靠 controller 内部拼接
Controller 方法名与 HTTP 方法、路径的自动映射规则
Iris 的 MVC 不是靠注解或配置文件驱动,而是严格依赖方法名前缀 + 首字母大写。写错大小写或少个字母,就完全不触发。
-
Get()→ 匹配GET /(当前 Party 根路径) -
GetUsers()→ 自动映射为GET /users,首字母小写的users是路径段 -
PostCreateOrder()→POST /create-order,驼峰自动转 kebab-case - 若需自定义路径(比如带参数),必须用
BeforeActivation:b.Handle("GET", "/user/{id:int}", "GetUser") - 不支持
getUsers(全小写)或GETUsers(双大写),会静默忽略
模板渲染失败的三个高频原因
app.RegisterView(iris.HTML("./web/views", ".html")) 看似简单,但路径、扩展名、控制器返回值三者必须严丝合缝,否则白屏无报错。
- 模板文件必须放在
./web/views目录下,且后缀名严格匹配注册时传入的".html"(不能是.tmpl或漏掉点) - controller 方法返回
string或error时,Iris 默认不走模板,而是直接输出字符串;要渲染模板,必须返回mvc.View类型:return mvc.View{"user/profile.html", user} -
View中第一个参数是相对路径,从./web/views开始算,不能写成./web/views/user/profile.html,否则报template: ... not found - 如果用了 layout,确保
Layout字段设对,且 layout 文件本身也在 views 目录下
Controller 之间共享依赖(如数据库连接、gRPC Client)的两种写法
别在每个 controller 里重复 sql.Open 或 grpc.Dial,Iris 提供了两层注入能力:MVC Application 级和 Controller 实例级。
- 全局注入(推荐):
mvcApp.Register(db).Register(cacheClient),然后在 controller 结构体中声明字段:DB *sql.DB `inject:""`,Iris 自动赋值 - 实例级注入(适合测试):在
Handle(new(MyController))前,先new(MyController).DB = db,再传入 - 字段标签必须是
`inject:""`,写成`inject:"db"`或漏掉反引号都会失效 - 注意:
Register必须在Handle之前调用,顺序颠倒则注入为空
真正麻烦的从来不是写第一个 controller,而是当你要加第二个、第三个,还要对接数据库、缓存、gRPC,并让它们在不同环境(dev/staging/prod)下稳定工作——这时候目录结构是否隔离、依赖是否可替换、错误是否可追踪,就全看初始化那几行代码有没有踩准 Iris 的契约。稍有偏差,debug 成本远高于重写。











