IHP 控制器与 Action 实战指南:从请求参数解析到响应渲染与重定向
IHP 控制器与 Action 实战指南:从请求参数解析到响应渲染与重定向
IHP 将 Web 应用的请求处理逻辑组织为 Controller(控制器)与 Action(动作):Action 是"发给应用的一条消息",Controller 是一组相关 Action 的集合。本文以 IHP 官方指南 Guide/controller.markdown 为骨架,结合仓库源码(IHP.ControllerSupport、IHP.Controller.Param、IHP.Controller.Render 等)与集成测试示例(integration-test/Web/Controller/Posts.hs),系统讲解如何定义控制器与 Action、读取查询参数与表单字段、处理生命周期、渲染各类响应、执行重定向,以及常见错误的排查方法。读完本文,你将能够在 IHP 项目中独立编写类型安全的控制器代码。
Action 的本质:消息与请求处理逻辑
在 IHP 中,Action 是请求处理逻辑的载体,而 Controller 只是相关 Action 的分组。你可以把 Action 想象成发送给应用的一条条消息:例如 ShowPostAction { postId :: Id Post } 就是"把 id 为 $postId 的帖子展示给我"这条消息。
每个 Action 都必须以数据结构的形式定义在 Web/Types.hs 中。这意味着,你只需要浏览这一个文件,就能概览"应用可以接收哪些消息"——这是 IHP 区别于传统框架(路由与处理器分散在多个文件)的显著设计。
以仓库中的集成测试项目为例,integration-test/Web/Types.hs 定义了完整的 PostsController:
data PostsController
= PostsAction
| NewPostAction
| ShowPostAction { postId :: !(Id Post) }
| CreatePostAction
| EditPostAction { postId :: !(Id Post) }
| UpdatePostAction { postId :: !(Id Post) }
| DeletePostAction { postId :: !(Id Post) }
deriving (Eq, Show, Data)
创建新 Controller
IHP 推荐使用代码生成器来创建新的控制器:
- Web GUI 方式:打开
http://localhost:8001/NewController(IHP IDE 提供的界面)。 - CLI 方式:运行
new-controller CONTROLLER_NAME。
下面的内容则演示手动创建的完整流程,帮助你理解代码生成器背后发生了什么。
第一步:在 Web/Types.hs 中定义类型
假设我们要创建一个只含单个 Action ShowPostAction 的控制器,首先在 Web/Types.hs 定义类型:
data PostsController
= ShowPostAction { postId :: !(Id Post) }
deriving (Eq, Show, Data)
ShowPostAction { postId :: !(Id Post) } 中的 postId 字段会在运行时被自动填充为请求 URL 中的 postId 参数——这一填充动作由 IHP 路由器自动完成。同时,IHP 要求控制器类型具备 Eq、Show 和 Data 实例,因此这里显式 deriving。从源码 ihp/IHP/ControllerSupport.hs 可以看到,Controller 类型类本身就以 Show 和 Eq 为约束:
class (Show controller, Eq controller) => Controller controller where
beforeAction :: (...) => IO ()
beforeAction = pure ()
action :: (...) => controller -> IO ResponseReceived
第二步:实现 Controller 实例
定义好"接口"后,需要在 Web/Controller/Posts.hs 中实现真正的请求处理逻辑,即 Controller 实例中的 action 函数:
module Web.Controller.Posts where
import Web.Controller.Prelude
instance Controller PostsController where
action ShowPostAction { postId } = renderPlain "Hello World"
该实现让 ShowPostAction 返回一段纯文本。action 的实现通常是对控制器所有 Action 的一个大型模式匹配。Web.Controller.Prelude 实际对应源码 ihp/IHP/ControllerPrelude.hs,它一次性导入了参数解析、渲染、重定向、认证、查询构建等控制器侧常用模块,无需逐个手动导入。
读取查询参数与请求体参数
在 Action 内部,用 param 函数访问请求参数。一个参数既可以是 URL 查询参数(如 ?paramName=paramValue),也可以是表单字段(如 <form><input name="paramName" value="paramValue"/></form>,此时称为请求体参数)。param 对两类参数一视同仁;当同名参数同时存在于查询和请求体时,请求体参数优先。
给定请求 GET /UsersAction?maxItems=50,可以这样读取 maxItems:
action UsersAction = do
let maxItems = param @Int "maxItems"
也可以改用表单提交:
<form action={UsersAction} method="POST">
<input type="text" name="maxItems" value="50" />
<button type="submit">Send</button>
</form>
值会被自动转型为 Int。这种解析开箱即用地支持 Id、UUID、Bool、Timestamp 等类型,例如:
action ExampleAction = do
let userName = param @Text "userName"
let timestamp = param @UTCTime "createdAt"
let userId = param @(Id User) "userId"
从源码 ihp/IHP/Controller/Param.hs 可以看到,param 底层委托给通用的 Wai.Request.Params 实现:
param :: (?request :: Request) => (ParamReader valueType) => ByteString -> valueType
param !name = Params.param ?request.parsedBody ?request name
缺失参数与容错读取
当参数解析失败时,param 会抛出异常并中断当前 Action。因此 IHP 提供了三档容错 API:
-
paramOrDefault:参数缺失时返回默认值;但参数存在而无法解析时仍然抛错——对表单字段而言,无法解析的值通常是一个值得关注的 bug:action UsersAction = do let maxItems = paramOrDefault @Int 50 "maxItems"源码实现见 ihp/IHP/Controller/Param.hs。
-
paramOrDefaultIgnoreInvalid:用于读取 URL 参数——那里可能是用户随手输入、旧链接遗留或爬虫猜出来的值。它对"缺失"和"无法解析"两种情况都回退到默认值:action UsersAction = do let page = paramOrDefaultIgnoreInvalid @Int 1 "page"于是
?page=abc会渲染第一页而不是报错页。实现见 ihp/IHP/Controller/Param.hs,其文档明确指出:优先对表单字段使用普通paramOrDefault(仍会抛错,让 bug 不被静默忽略),URL 参数才使用本函数。 -
paramOrNothing:参数缺失时返回Nothing,存在时返回Just theValue:let page = paramOrNothing @Int "page" -- :: Maybe Int
除此之外,ihp/IHP/Controller/Param.hs 还提供了 paramOrError(返回 Either ParamException valueType)、hasParam(仅判断参数是否存在)、queryOrBodyParam(返回未解析的原始 ByteString)、allParams(返回请求的全部参数),以及免去类型注解的便捷函数 paramText / paramInt / paramBool / paramUUID。
同名多值参数(复选框场景)
处理复选框时,同一个参数名下往往有多个值。给定如下表单:
<h1>Pancake</h1>
<input name="ingredients" type="checkbox" value="milk" /> Milk
<input name="ingredients" type="checkbox" value="egg" /> Egg
当 Milk 和 Egg 都被勾选时,用 param @Text "ingredients" 只会拿到第一个值 "Milk"。要读取全部勾选项,使用 paramList:
action BuildFood = do
let ingredients = paramList @Text "ingredients"
两个复选框都勾选时 ingredients 为 <a href="https://link.gitcode.com/i/a6d9535cf58c2682a3ed4c3494f1a97b" target="_blank">"milk", "egg"];一个都不勾选时返回空列表。与 param 相同,paramList 也开箱即用地支持 Id、UUID、Bool、Timestamp 等类型。源码实现见 [ihp/IHP/Controller/Param.hs。
与之配套的还有 paramListOrNothing(ihp/IHP/Controller/Param.hs),对同名的多个字段返回 [Maybe valueType],用于处理"部分字段为空值"的提交场景。
把数据从 Action 传给 View
把数据传给视图渲染是常见需求,做法是扩展视图数据结构。初始状态如下:
action ExampleAction = do
render ExampleView { .. }
data ExampleView = ExampleView { }
instance View ExampleView where
html ExampleView { .. } = [hsx|Hello World!|]
现在要把用户名字传给视图,只需给 ExampleView 增加一个 firstname :: Text 字段,并在 HSX 中加入 {firstname}:
data ExampleView = ExampleView { firstname :: Text }
instance View ExampleView where
html ExampleView { .. } = [hsx|Hello World, {firstname}!|]
此时编译器会立刻提示:Action 里还没有定义 firstname 字段。所以同步更新 Action:
action ExampleAction = do
let firstname = "Tester"
render ExampleView { .. } -- 注意:ExampleView { .. } 只是 ExampleView { firstname = firstname } 的简写
也可以让它更动态,允许用户通过查询参数指定名字:
action ExampleAction = do
let firstname = paramOrDefault @Text "Unnamed" "firstname"
render ExampleView { .. }
这样在不传 firstname 参数时,页面会渲染出 Hello World, Unnamed!。
在控制器与视图中访问 FrameworkConfig
Config/Config.hs 中定义的配置可以通过隐式参数 ?context 在控制器内访问:
action MyAction = do
let config = ?context.frameworkConfig
框架还基于该隐式参数提供了便捷判断函数,如 isDevelopment / isProduction:
action MyAction = do
when isDevelopment (putStrLn "Running in dev mode")
这两个函数的实现位于 ihp/IHP/FrameworkConfig.hs,本质是比较 frameworkConfig.environment 与 Development / Production 环境值。集成测试项目的配置示例可见 integration-test/Config/Config.hs:option Development 与 option (AppPort 8000)。
进阶:使用自定义类型
偶尔你需要解析 param 尚不支持的自定义标量类型。此时可以自定义一个 ParamReader 实例,即可让 param 系列函数支持你的类型。ParamReader 的现有实例列表可查阅 ihp/IHP/Controller/Param.hs,其中包含 PostgreSQL 相关的 Point(格式 '1,2')、Interval、Inet(IP 地址)、Polygon(至少 3 个点)以及 Id(基于 PrimaryKey 的 ParamReader 实例)。此外,对于枚举类型,源码还提供了现成的默认实现 enumParamReader 与 enumParamReaderJSON(ihp/IHP/Controller/Param.hs):
data Color = Yellow | Red | Blue deriving (Enum)
instance ParamReader Color where
readParameter = enumParamReader
readParameterJSON = enumParamReaderJSON
用 fill 从表单填充记录
操作记录时,应使用 fill 而非逐个 param 调用。fill 会自动处理校验失败——例如某字段本应是整数,而提交值不是数字时,它会将该解析错误附加为记录的校验错误,而不是直接抛异常中断请求。
典型示例(对应 ihp/IHP/Controller/Param.hs 中 FillParams 类型类的用法):
action CreatePostAction = do
let post = newRecord @Post
post
|> fill @'["title", "body"]
|> ifValid \case
Left post -> render NewView { .. }
Right post -> do
post <- post |> createRecord
setSuccessMessage "Post created"
redirectTo PostsAction
上述代码创建一条新 Post 记录,然后用请求中的 title 与 body 填充。若请求数据非法,重新渲染 NewView 让用户修正错误;若数据合法,则创建记录并重定向到 PostsAction。fill 的容错细节从源码可见:解析失败会调用 attachFailure 挂载校验错误并继续解析其余字段,参数缺失则直接跳过该字段。
ifValid 的实现见 ihp/IHP/Controller/Param.hs:根据记录是否通过校验,把记录交给 Left 或 Right 分支。仓库集成测试项目中的实际用法见 integration-test/Web/Controller/Posts.hs,其 buildPost 组合了 fill @'<a href="https://link.gitcode.com/i/14e6e2eac52173865ea32261c9739880" target="_blank">"title", "body", "userId"] 与 validateField #title nonEmpty。另一个实用工具是 emptyValueToNothing,它把空字符串转换为 Nothing,避免可选字段被存成空串而非 NULL(源码见 [ihp/IHP/Controller/Param.hs)。
生命周期:beforeAction
Controller 实例还提供 beforeAction 函数,它在 action 之前被调用(默认实现为 pure ())。认证等通用请求处理逻辑通常放在 beforeAction 中,从而保护控制器的所有 Action 免于未授权访问。
生命周期示例:
instance Controller PostsController where
beforeAction = putStrLn "A"
action ShowPotsAction { postId } = putStrLn "B"
调用 ShowPostAction 时,服务器控制台会依次输出:
A B
认证示例:
instance Controller PostsController where
beforeAction = ensureIsUser
action ShowPostAction { postId } = ...
从源码 ihp/IHP/ControllerSupport.hs 可以看到 runAction 的执行顺序:先绑定 ?theAction 与 ?request 隐式参数,必要时准备行级安全(RLS)模型上下文,然后依次调用 beforeAction 与 action controller。另外,框架还支持 initContext(在每次请求初始化时运行,默认无操作),典型用途是在 Web/FrontController.hs 中设置默认布局,见 integration-test/Web/FrontController.hs。
访问当前 Action 与当前请求
在 beforeAction 与 action 内部,可以通过特殊变量 ?theAction 访问当前 Action。该变量以隐式参数传递,编写控制器辅助函数时非常有用。
IHP 遵循 Haskell WAI 标准处理 HTTP 请求与响应,可以用 request 获取 WAI Request 数据结构(源码 ihp/IHP/ControllerSupport.hs),并在此基础上提供若干常用快捷方式:
action ExampleAction = do
-- 当前请求路径(如 /Users)
putStrLn ("Current request url: " <> tshow getRequestPath)
-- 路径附带全部参数(如 /ShowUser?userId=...)
putStrLn ("Current request url: " <> tshow getRequestPathAndQuery)
-- 读取请求体
body <- getRequestBody
-- 获取原始请求
let theRequest = request
这些快捷方式的底层实现均可在 ihp/IHP/ControllerSupport.hs 中找到:getRequestPath 直接读取 rawPathInfo(L266-L269),getRequestPathAndQuery 拼接 rawPathInfo 与 rawQueryString(L271-L274),getRequestBody 读取 parsedBody.rawPayload(L262-L264)。
请求头
用 getHeader 读取请求头:
action ExampleAction = do
let userAgent = getHeader "User-Agent"
请求未提供 User-Agent 头时,userAgent 为 Nothing;否则为 Just "the user agent value"。头部名称查找不区分大小写——从源码看,它使用 Data.CaseInsensitive.mk 对名称做规范化后查表(ihp/IHP/ControllerSupport.hs)。
用 setHeader 设置响应头:
action ExampleAction = do
setHeader ("Max-Age", "10")
setHeader 的实现把响应头写入请求 vault 中的 IORef(ihp/IHP/ControllerSupport.hs),最终在 respondWith 时通过 addResponseHeadersFromContext 合并进响应(见 ihp/IHP/Controller/Response.hs)。
渲染响应
渲染视图(HTML)
控制器内发送响应的最常见方式是用 render 配合 View 数据结构:
render ShowPostView { .. }
render 把视图渲染为 HTML(源码 ihp/IHP/Controller/Render.hs)。若需要基于 Accept 请求头同时支持 HTML 与 JSON,改用 renderHtmlOrJson——这要求视图同时实现 View 与 JsonView 实例,细节可参考 JSON API 指南。其实现(ihp/IHP/Controller/Render.hs)会解析 Accept 头,在 text/html 与 application/json 之间选择,均不可接受时返回 406。
渲染纯文本
调用 renderPlain 发送纯文本响应:
action ExampleAction = do
renderPlain "My output text"
实现上,它用 responseLBS status200 配上 text/plain 内容类型(ihp/IHP/Controller/Render.hs)。
内联渲染 HTML
通常 HTML 应通过视图渲染(见上文"渲染视图")。但有时你想在 Action 内联输出 HTML,此时调用 respondHtml:
action ExampleAction = do
respondHtml [hsx|<div>Hello World</div>|]
需要先在控制器中导入 hsx:import Web.Controller.Prelude(它已重导出 IHP.HSX.MarkupQQ 的 hsx,见 ihp/IHP/ControllerPrelude.hs)。源码实现(ihp/IHP/Controller/Render.hs)直接用 responseBuilder 传递 Builder,避免中间惰性 ByteString 分配。同模块还有 respondSvg、renderXml、renderJson、renderJsonWithStatusCode 等响应函数。
渲染静态文件
用 renderFile 响应静态文件:
action ExampleAction = do
-- 让代码同时兼容 Static 与 S3 两种存储类型
let storagePrefix = case storage of
StaticDirStorage -> "static/"
_ -> ""
renderFile (storagePrefix <> "terms.pdf") "application/pdf"
其实现(ihp/IHP/Controller/Render.hs)基于 WAI 的 responseFile,以 200 状态码发送指定路径文件。
渲染"未找到"消息
当实体找不到时,用 renderNotFound 渲染通用 404 页面:
action ExampleAction = do
renderNotFound
从源码 ihp/IHP/Controller/NotFound.hs 可以看到,它会检查项目根目录下是否存在 static/404.html:存在则渲染该自定义页面,否则渲染 IHP 默认 404 页。同模块还提供 notFoundWhen / notFoundUnless 条件守卫,以及配套的 renderAccessDenied(403 页面,同样支持 static/403.html 自定义,见 ihp/IHP/Controller/AccessDenied.hs)。
重定向
重定向到 Action
用 redirectTo 重定向到另一个 Action:
action ExampleAction = do
redirectTo ShowPostAction { postId = ... }
需要传递自定义查询参数时不能用 redirectTo,请参考下文"重定向到路径"。重定向使用 HTTP 状态码 302,baseUrl 取自 Config/Config.hs 中的 FrameworkConfig;开发模式下 baseUrl 可能未配置,此时默认为 localhost(相关默认值逻辑见 ihp/IHP/FrameworkConfig.hs,IHP_BASEURL 环境变量可覆盖硬编码的 base url)。
如果需要强制后续请求为 GET(例如发生在 POST 或 DELETE 之后),用 redirectToSeeOther 发送 303 See Other:
action ExampleAction = do
redirectToSeeOther ShowPostAction { postId = ... }
源码中 redirectTo 通过 HasPath 类型类的 pathTo 把 Action 转成路径(ihp/IHP/Controller/Redirect.hs),pathTo 的定义见 ihp-router/IHP/Router/UrlGenerator.hs;redirectToSeeOther 则换成 status303(L42-L44)。
重定向到路径
要在同域内重定向到某个路径,用 redirectToPath:
action ExampleAction = do
redirectToPath "/blog/wp-login.php"
它也可以用来给 Action 附加查询参数:
action ExampleAction = do
redirectToPath ((pathTo ShowPostAction { .. }) <> "&details=on")
用 redirectToPathSeeOther 发送 303 重定向到路径:
action ExampleAction = do
redirectToPathSeeOther "/blog/wp-login.php"
实现上,redirectToPath 用 Approot.getApproot ?request 得到当前 baseUrl 后拼接路径(ihp/IHP/Controller/Redirect.hs)。
重定向到外部 URL
用 redirectToUrl 重定向到外部 URL:
action ExampleAction = do
redirectToUrl "https://example.com/hello-world.html"
用 redirectToUrlSeeOther 发送 303 重定向:
action ExampleAction = do
redirectToUrlSeeOther "https://example.com/hello-world.html"
两个函数内部都会 parseURI 解析 URL 并调用 WAI 的 redirect 构造响应,分别使用 status302 / status303(ihp/IHP/Controller/Redirect.hs)。同模块还提供基于 Referer 头的 redirectBack 与 redirectBackWithFallback,前者在缺少 Referer 时回退到 /(L119-L145)。
Action 执行模型与提前返回
像 render、redirectTo、renderJson 这类响应函数会把响应发给客户端,并返回 IO ResponseReceived。由于 action 的返回类型就是 IO ResponseReceived,响应函数通常是 Action 中的最后一个表达式:
action ExampleAction = do
post <- fetch postId
render ShowView { .. }
提前返回(Early Return)
需要提前退出 Action 时,使用 earlyReturn:它发送响应并停止执行 Action 剩余代码:
action ExampleAction = do
when (not loggedIn) do
earlyReturn (redirectTo LoginAction)
-- 只有 loggedIn 为 True 时才会执行到这里
render MyView
从源码 ihp/IHP/Controller/Response.hs 可见,respondAndExit 本质是 earlyReturn (respondWith response)——先发送响应再抛出 EarlyReturnException 短路当前 Action,由 earlyReturnMiddleware 捕获处理。
访问控制场景请直接使用内置的 accessDeniedUnless / accessDeniedWhen,它们会替你处理提前返回(403):
action EditPostAction { postId } = do
post <- fetch postId
accessDeniedUnless (post.authorId == currentUserId)
render EditView { .. }
实现见 ihp/IHP/Controller/AccessDenied.hs:条件不满足时 earlyReturn renderAccessDenied。当你手工构造了一个 Response 后,可以用 respondAndExit 发送响应并停止执行。
关于提前返回机制,仓库测试 ihp/Test/Test/ControllerSupportSpec.hs 也有相应验证:例如 requestBodyJSON 在 JSON 体缺失或解码失败时会调用 earlyReturn 返回 400,测试通过 earlyReturnMiddleware 包裹的应用来断言这一行为。
Controller 上下文与 Request Context
Actions 可以通过控制器上下文访问 Request Context:
let requestContext = ?context.requestContext
Request Context 提供对 WAI 请求、请求的查询与表单参数、上传文件等信息的访问。它通常被其他函数用来提供高层功能——例如 getHeader 就是借助 Request Context 读取请求头的。
文件上传
文件上传是独立主题,请参阅 File Storage & Uploads 指南。
常见问题排查(Troubleshooting)
报错:"Variable not in scope: action"
Variable not in scope: action :: ShowPostAction -> IO ()
原因:忘了把 Action 构造函数加进 Web/Types.hs 的控制器数据类型。控制器处理的每个 Action 都必须作为构造函数列出:
data PostsController
= ShowPostAction { postId :: !(Id Post) }
| PostsAction -- 新加 Action 别忘了写在这里
deriving (Eq, Show, Data)
参数缺失错误
param: Parameter 'title' not found in the request
原因:调用了 param @Text "title",但请求中不含 title 参数。用 paramOrDefault 提供回退值,或用 paramOrNothing 显式处理缺失情况:
let title = paramOrDefault @Text "" "title"
let title = paramOrNothing @Text "title" -- 返回 Maybe Text
报错:"No instance for (Controller ...)"
No instance for (Controller PostsController)
原因:在 Web/Types.hs 定义了控制器类型,却忘了在 Web/Controller/Posts.hs 实现 Controller 实例:
instance Controller PostsController where
action ShowPostAction { postId } = do
...
使用 param 时出现 "Ambiguous type variable"
Ambiguous type variable 'a0' arising from a use of 'param'
原因:编译器无法推断参数应被解析成什么类型。补充类型注解:
-- 错误:let value = param "id"
let value = param @Int "id" -- 正确
let value = param @(Id Post) "id" -- 正确
Action 未被调用(404 Not Found)
如果 Action 返回 404,检查两点:
-
Web/Routes.hs中缺少路由:确保控制器类型有AutoRoute实例:instance AutoRoute PostsController -
Web/FrontController.hs未注册控制器:控制器必须加入前端控制器的controllers列表:instance FrontController WebApplication where controllers = [ -- ... , parseRoute @PostsController -- 加上这一行 ]
仓库集成测试项目的完整写法见 integration-test/Web/FrontController.hs:controllers = [ parseRoute @PostsController ]。
在错误的上下文中执行 IO 导致的类型错误
Couldn't match type 'IO' with 'IO'
这个令人困惑的错误通常意味着你在"期望控制器 Action 的位置"运行了普通 IO 操作,或者反过来。控制器 Action 运行在一个能访问请求与响应的特殊上下文中。如果需要在控制器内调用普通 IO 函数,请使用 liftIO,或检查函数签名是否与期望类型匹配。
小结
IHP 的控制器体系以"类型即路由"为核心:在 Web/Types.hs 用代数数据类型声明 Action 集合,在 Web/Controller/*.hs 用 Controller 实例的模式匹配实现请求处理。参数读取(param 系列与 fill)、生命周期钩子(beforeAction)、响应渲染(render / renderPlain / respondHtml / renderFile / renderNotFound)、重定向(redirectTo 系列与 303 变体)以及提前返回(earlyReturn / accessDeniedUnless / respondAndExit)共同构成了完整、类型安全且高度可组合的请求处理体系。结合 ihp/IHP/ControllerPrelude.hs 的一次性导入,你几乎不需要关心底层 WAI 细节,就能快速构建出健壮的 Web 控制器层。