Iris需在路由注册前用app.OnErrorCode绑定404和500处理器;404可渲染HTML模板或推荐相似路径(需判空降级);500函数须设StatusCode(500)、隐藏敏感信息并记录日志。

当用户访问不存在的路由或服务器内部出错时,Iris默认返回简陋的纯文本错误信息,无法体现品牌风格或引导用户操作。你需要为404和500状态码分别绑定自定义响应逻辑,且必须在注册常规路由之前完成错误处理器注册,否则请求会直接落入默认兜底流程而跳过你的处理函数。
注册404和500错误处理器
在app := iris.New()之后、app.Get(...)等路由注册之前,调用app.OnErrorCode两次:一次传入iris.StatusNotFound(即404),一次传入iris.StatusInternalServerError(即500)。
这一步不能颠倒顺序——如果先注册了/user/{id}这类泛匹配路由,再注册404处理器,Iris可能因路由匹配优先级问题根本不会触发你的404函数。
确保app.OnErrorCode调用在app.Run()之前,且早于所有app.Get/app.Post等路由声明。
编写404处理函数
方法一:渲染HTML模板
在views/errors/404.html路径下创建模板文件,内容可包含搜索框、首页链接和友好的插画;处理函数中调用ctx.View("errors/404.html")即可。
方法二:动态推荐相似路径
调用ctx.FindClosest(3)获取最多3个拼写相近的已注册路径,遍历生成HTML列表返回给用户。注意:该方法仅对路径字符串做编辑距离计算,不校验HTTP方法,所以GET /api/users可能被推荐给POST /api/user请求。
【必须检查ctx.FindClosest返回切片长度,为空时要降级输出纯文本,否则页面会空白】
编写500处理函数
第一步:定义处理函数签名
函数必须接收iris.Context参数,不可省略,否则编译失败。
第二步:避免暴露敏感信息
不要在响应体中打印err.Error()或堆栈,而是统一返回“服务暂时不可用”,同时用app.Logger().Errorf记录完整错误到日志文件。
第三步:设置响应头
手动调用ctx.StatusCode(500)确保状态码正确,否则浏览器可能缓存200响应导致SEO异常。
这一步操作起来很简单,直接在函数开头加一行ctx.StatusCode(500)就行。
验证错误页面是否生效
① 启动服务后,直接在浏览器访问一个明显不存在的路径,例如/this-route-does-not-exist,确认看到自定义404页面而非“404 page not found”纯文本。
② 创建一个故意panic的路由:app.Get("/panic-test", func(ctx iris.Context) { panic("test panic") }),访问该路径,观察是否返回你定义的500内容而非Iris默认崩溃页。
③ 使用curl命令验证状态码:curl -I http://localhost:8080/nonexistent,检查响应头中HTTP/1.1 404 Not Found是否出现。


















