测试接口测试性能测试Mock【免费下载链接】karateTest Automation Made Simple项目地址https://gitcode.com/gh_mirrors/ka/karate点击查看免费下载本文是 Karate 开源仓库中 docs/TEMPLATING.md 的深度解读与实战指南。Karate 的模板引擎以Thymeleaf 属性语法为骨架但将表达式语言替换为原生 JavaScript并在此基础上扩展出ka:*专属属性服务端脚本、HTMX 请求映射、Alpine.js 数据桥接同时支持服务端模式HTTP 服务器 会话 HTMX Alpine.js与静态模式独立 HTML 生成。读完本文你将掌握th:/ka:全部核心属性、request/session/context/response四大内建对象、ServerConfig完整配置项、Shell 布局模板、CSRF 防护、JS API Handler 以及从 Karate Feature 中调用模板的完整链路。两种运行模式与表达式语言定位TEMPLATING.md 将引擎明确划分为两种模式Server mode服务端模式——以HttpServerServerConfig驱动提供完整 HTTP 语义会话session、CSRF、HTMX 局部刷新、Alpine.js 数据绑定、服务端脚本等。这是构建 Web 应用的主战场。Static mode静态模式——不启动 HTTP 服务器仅用EngineMarkupConfig将模板渲染为纯 HTML 字符串适用于报告、邮件等离线场景。两种模式共享同一套th:*属性体系差异在于内建对象与 HTMX /ka:nocache等功能的可用性静态模式没有request/response/session不做 HTMX 处理ka:nocache被忽略。表达式语言方面该引擎刻意不使用 OGNL / SpEL而是使用 JavaScript。这意味着属性值里写的是items.length而非items.size()条件判断支持真正的if/else与?.可选链等 JS 语法。这一设计与 Karate 全栈「同一门语言JS」的理念一脉相承——模板逻辑、服务端脚本、API Handler 全部用 JS 表达。th:属性兼容 Thymeleaf 语法的核心渲染指令th:*属性是模板渲染的主力TEMPLATING.md 给出了完整清单属性用途示例th:text设置文本内容HTML 转义th:textuser.nameth:utext设置文本内容不转义——仅用于可信 HTMLth:utextrenderedHtmlth:if/th:unless条件渲染th:ifuser.adminth:each循环状态变量iter提供.index、.count、.first、.last、.even、.oddth:eachitem, iter: itemsth:attr设置任意属性带连字符的属性名要加引号th:attrdata-id: item.idth:class/th:classappend设置 / 追加 classth:classappendactive ? on : th:id、th:value、th:action、th:title等设置对应 HTML 属性th:actioncontext.templateth:with声明局部变量注意用:而非th:withtotal: price * qtyth:insert在宿主元素内部插入片段th:insertheaderth:replace用片段替换宿主元素th:replace~{header :: nav}th:fragment定义具名片段th:fragmentnav几个容易被忽略但决定行为差异的细节片段路径自动包装。简单路径会自动包上~{}th:insertheader等价于th:insert~{header}具名片段仍需显式语法~{header :: nav}。也就是说直接写文件名即可插入整个模板文件只有需要精确定位到某段具名片段时才写完整形式。真值判定遵循 Thymeleaf 而非 JS。空字符串是真值truthy而false、off、no是假值。这与 JS 的Boolean() false完全相反是最容易踩坑的点。判断「非空字符串」请显式写成str.length 0。Map 迭代自动转换。遍历 Map 对象时引擎自动将其转换为[{key, value}]条目数组配合th:each可像遍历普通列表一样访问item.key与item.value。Karate 专属属性ka:*服务端能力在 Thymeleaf 兼容层之上Karate 扩展了三个专属属性属性用途ka:scopeglobal在服务器端运行script中的 JavaScript通过_.foo设置的变量可被后续表达式访问ka:scopelocal同上但作用域限定在每次th:each迭代内ka:setname把块内容捕获为变量ka:nocachetrue给src/href追加?tsepoch-ms实现缓存破除仅服务端模式典型用法——在模板中先执行服务端脚本查询数据再用th:each渲染script ka:scopeglobal _.items db.findItems(); /script tr th:eachitem: items td th:textitem.nameName/td /tr从实现看KaScriptProcessor.javaka:scopelocal走kec.evalLocal(text)ka:scopeglobal走kec.evalGlobal(text)并随后触发maybeDispatchAction()——这解释了为什么全局作用域脚本能承载「重定向、写会话」这类动作型副作用而局部作用域只负责迭代内的数据准备。若脚本带有src属性则交由KaScriptSrcProcessor处理并忽略内联脚本体。服务端 JavaScript_.变量与动作脚本服务端脚本通过_.foo value设置模板变量之后在表达式中可直接以foo访问同时request、session、context、response四个内建对象直接可用无需任何前缀。script ka:scopeglobal if (request.post) { db.save(request.paramJson(form)); context.flash.success Saved; context.redirect(/items); } _.items db.findAll(); /script这个片段展示了典型的POST-Redirect-GETPRG模式表单提交时保存数据、设置 flash 消息、重定向GET 请求时加载数据渲染列表。Java 互操作同样开放模板脚本中可用Java.type(java.text.SimpleDateFormat)直接构造 JVM 类——前提是引擎的 Java 互操作桥接被允许ServerConfig.engineSupplier(...)支持传入自定义ExternalBridge以限制可访问的 Java 类默认全部可访问见 ServerConfig.java。四大内建对象详解request布尔标志get、post、put、delete、ajax属性method、path、url、urlBase、params、headers、body、bodyString、multiParts、pathParams方法param(name)/param(name, default)—— 取查询参数带默认值paramInt(name)—— 取整型参数paramJson(name)—— 将参数解析为 JSON表单中JSON.stringify出来的对象字段用它还原paramValues(name)—— 取多值参数数组header(name)—— 取请求头pathMatches(pattern)—— 路径模式匹配配合子路径路由提取参数如/items/{id}multiPart(name)—— 取 multipart 文件response属性status、bodyMap / List 会自动序列化为 JSON、headerssession在context.init()之前为null可读写任意键delete session.user删除键。API 请求不会自动创建会话需自行session || context.init()。context属性template、sessionId、flash、csrf方法init()、close()、redirect(path)、switch(template)、uuid()、log(...)、read(path)、toJson(obj)、fromJson(str)控制流信号语义重要redirect(path)与switch(template)会抛出一个内部TemplateFlowSignal从而中止当前模板渲染——其后的语句不会执行模板其余部分不会渲染。redirect会发送 302switch则改为渲染替换后的模板。这也是为什么示例代码里要把context.redirect(...)放在脚本最后后面的代码根本不会运行不应依赖它之后的状态。HTMX 集成ka:*编译为hx-*服务端模式下ka:属性会编译为hx-*属性并附带两层预处理——URL 解析模板名 → 路由 URL、自动前置contextPath与表达式求值动态值。对于纯透传场景直接写hx-*即可。属性用途ka:get、ka:post、ka:put、ka:patch、ka:delete将模板名解析为 URL 并前置contextPaththis表示当前页面ka:vals求值 JS 表达式 → JSON 单引号包裹的hx-vals写法为action:x,id:item.id不带花括号ka:dataAlpine 的x-data绑定在form上还会注入携带JSON.stringify(var)的隐藏输入其余所有 HTMX 属性hx-target、hx-swap、hx-trigger、hx-confirm、hx-push-url、hx-boost、hx-include、hx-select、hx-indicator、hx-ext、hx-disabled-elt等直接以hx-*书写引擎不会干预。两个易踩坑点ka:vals与表单提交按钮放在 HTMX 表单内提交按钮上的ka:vals会被静默丢弃action 参数应改用隐藏input携带。URL 解析规则ka:get等属性值支持this解析为当前模板去掉.html后缀的路径与${...}动态表达式。从 HxMethodProcessor.java 源码可见以/开头的 URL 会前置contextPath含${的值会被放入 JS 模板字符串求值。通用透传属性则由 HxGenericProcessor.java 统一改写为hx-name如ka:target→hx-target。Alpine.js 数据绑定ka:data双端桥接ka:data是服务端初始数据与前端 Alpine 状态之间的桥梁。TEMPLATING.md 给出的完整示例script ka:scopelocal _.initialForm { email: , role: user }; /script form ka:dataform:initialForm ka:postsave input x-modelform.email/ button typesubmitSave/button /form语法为ka:datavarName:serverExpression。其行为分两种任意元素添加x-data{ varName: {...} }——刻意用单引号包裹属性保证内部 JSON 的双引号安全内嵌。form元素额外注入input typehidden namevarName x-bind:valueJSON.stringify(varName)/服务端用request.paramJson(form)读取回传的表单对象。从 KaDataProcessor.java 的实现看处理器会用Json.stringifyStrict(initialData)把服务端表达式的求值结果序列化进x-data表单隐藏输入则绑定x-bind:valueJSON.stringify(form)动态同步。如此前端编辑、提交、服务端还原整个表单状态在双端保持一致的 JSON 形态。Server-Sent EventsSSE推送服务端模式通过SseHandler提供 SSE 推送TEMPLATING.md 给出的最小可运行示例SseHandler sseHandler (request, connection) - { Thread.ofVirtual().start(() - { while (connection.isOpen()) { connection.send(status, {\active\:3}); Thread.sleep(1000); } }); }; HttpServer.start(port, requestHandler, sseHandler);SseConnection的方法集send(event, data)、send(data)、sendComment(text)、close()、isOpen()、onDisconnect(cb)。关键语义SSE 端点绕过ServerRequestHandler——不建立会话、不做 CSRF、也没有模板上下文。也就是说 SSE 连接是无状态、无防护的原始通道适合状态机/进度推送等场景推送逻辑里需要的用户信息应在握手时自行携带。API Handlers纯 JS 的 REST 端点api/目录下的普通.js文件即为 API 处理器ServerConfig中配置的全局变量在处理器内同样可用。TEMPLATING.md 的示例// api/items.js if (request.get) { var id request.paramInt(id); response.body id ? db.findById(id) : db.findAll(); } if (request.post) { response.body db.create(request.body); response.status 201; }子路径路由/api/todos/abc会匹配api/todos.js此时request.path为/todos/abc用request.pathMatches(/{resource}/{id})提取路径参数。会话语义API 请求不会自动创建会话需要会话时显式写session || context.init()。这也是 webhook、公开接口等场景下配合context.setSession(Session.TEMPORARY)的无状态范式。此外ServerConfig.jsRoute(pattern, jsFile)允许把 JS 端点注册到任意路径不局限于/api/前缀适用于「需要放在某鉴权前缀内部」的下载/数据端点例如.jsRoute(/team/export, team/export.js)且原请求路径会保留处理器仍可用request.pathMatches()提取参数见 ServerConfig.java。服务端搭建ServerConfig完整配置参考最小启动代码ServerConfig config new ServerConfig() .resourceRoot(classpath:web) .sessionStore(new InMemorySessionStore()) .devMode(true) .globalVariables(Map.of(utils, new AppUtils(db))); HttpServer.start(8080, new RequestHandler(config, resolver));ServerConfig选项总表默认值以当前仓库源码为准选项默认值用途resourceRoot(path)—模板与静态资源根目录contextPath(path)URL 前缀devMode(bool)false热重载、禁用缓存devTrace(bool)环境变量KARATE_DEV_TRACEtrue预置在每次th:insert/th:replace解析处输出片段追踪 HTML 注释便于调试模板组合要求devModetrue才生效生产模式静默忽略见 ServerConfig.javasessionStore(store)null会话存储null表示不启用会话sessionExpirySeconds(sec)600会话 TTLsessionCookieName(name)karate.sid会话 Cookie 名sessionSameSite(s)SameSite.LAX会话 Cookie 的 SameSiteOAuth/OIDCresponse_modeform_post场景需切NONE自动附带Securedev 模式外csrfExemptPaths(...)—CSRF 豁免路径精确匹配OAuth form_post 回调、带签名校验的 webhook 等合法跨站 POSTapiPrefix(prefix)/api/.js处理器 URL 前缀staticPrefix(prefix)/pub/静态文件 URL 前缀csrfEnabled(bool)trueCSRF 防护开关allowedOrigins(...)—CORS 允许来源securityHeadersEnabled(bool)trueX-Frame-Options、X-Content-Type-Options等安全头xFrameOptions(value)DENYX-Frame-Options 值referrerPolicy(value)strict-origin-when-cross-originReferrer-Policy 值contentSecurityPolicy(csp)null自定义 CSP 头hstsEnabled(bool)/hstsMaxAge(sec)/hstsIncludeSubDomains(bool)false/31536000/trueHSTS 头及其参数errorTemplate404(path)/errorTemplate500(path)—自定义 404 / 500 模板templateRoute(pattern, template)—路径模式 → 模板映射如/items/{id}→detail.html优先于文件解析需先注册更具体的模式jsRoute(pattern, jsFile)—路径模式 → JS 处理器映射见上文shellTemplate(path)null全页面导航的布局外壳模板rawPaths(...)—自带完整 HTML 外壳、不做 shell 包装的路径精确匹配请求路径典型如/signin、/signoutrequestInterceptor(consumer)—预处理钩子requestFilter(fn)—返回非 null 的HttpResponse即可短路请求鉴权门运行于会话加载后、CSRF 校验前logHandler(consumer)—日志消费回调engineSupplier(supplier)—自定义 JSEngine供应器可限制 Java 互操作globalVariables(map)—注入所有模板与 API 处理器的全局变量会话时间单位提醒容易踩坑Session.getCreated() / getUpdated() / getExpires()返回的是epoch 秒UTC而非毫秒。这样设计让expires字段可直接用作 DynamoDB 的TimeToLiveSpecification属性——DDB 只在值以秒为单位时清扫行毫秒值会被静默忽略被当作公元 58,200 年。因此自定义SessionStore实现必须使用Instant.now().getEpochSecond()绝不能使用System.currentTimeMillis()。Shell 布局模板设置shellTemplate(path)后服务器先渲染内容模板其ka:scope副作用——flash、session、switch、redirect——先行提交再用 shell 包裹全页面导航。shell 可接收两个额外变量content—— 已渲染的内容 HTML用th:utextcontent插入因为它是可信 HTMLcontentTemplate—— 内容模板的解析路径如items.html跳过 shell 包装的四种情况请求携带HX-Request: trueHTMX 局部刷新、路径命中rawPaths、内容经context.redirect()短路、解析出的模板恰好等于 shell 本身防递归兜底。API 与静态响应永远不会被包装。new ServerConfig(resourceRoot) .shellTemplate(layout.html) .rawPaths(/signin, /signout);模板路由优先级/pub/*→ 静态文件/api/*→.js处理器其余全部 → HTML 模板按以下顺序解析已注册的templateRoute模式→文件查找/foo→foo.html→目录索引回退/foo→foo/index.html。templateRoute的映射优先级最高且原请求路径被保留模板内可用request.pathMatches()提取参数。CSRF 防护默认开启。只需在 shell / 布局中注入一次 token并用一个小的客户端脚本把 token 附加到每次 HTMX 请求头meta namecsrf-token th:contentcontext.csrf.token/ script document.body.addEventListener(htmx:configRequest, function(e) { var t document.querySelector(meta[namecsrf-token]); if (t) e.detail.headers[X-CSRF-Token] t.content; }); /scriptcontext.csrf暴露当前会话的 CSRF token。对于 OAuth form_post 回调、webhook 这类合法跨站 POST可用csrfExemptPaths(...)精确豁免如/signin并依靠 OAuthstate参数或签名头自行完成防伪校验ServerConfig.java。全局变量与SimpleObject桥接globalVariables(map)注入的变量对所有模板与 API 处理器可见。当全局变量是一个带方法的 Java 对象时实现SimpleObject接口即可把 Java 方法暴露给 JSpublic class AppUtils implements SimpleObject { Override public Object jsGet(String name) { return switch (name) { case findUser - (JsCallable) (ctx, args) - db.findUser(args[0].toString()); default - null; }; } Override public CollectionString keys() { return List.of(findUser); } } config.globalVariables(Map.of(utils, new AppUtils(db)));模板中即可调用utils.findUser(alice)。JS → Java 的类型转换规则为number→Numberstring→Stringboolean→Booleannull/undefined→null数组 →ListObject对象 →MapString, Object。静态 HTML 生成报告 / 邮件无需 HTTP 上下文时用静态模式生成独立 HTMLEngine engine new Engine(); MarkupConfig config new MarkupConfig(); config.setResolver(new ClasspathResourceResolver()); config.setServerMode(false); Markup markup Markup.init(engine, config); String html markup.processPath(report.html, Map.of(title, Q3, items, list));注意 MarkupConfig.java 中serverMode默认值为true向后兼容静态生成必须显式setServerMode(false)。静态模式下没有request/response/session没有HTMX 处理ka:nocache被忽略——纯粹的模板 → 字符串渲染管线。从 Karate Feature 调用模板doc关键字模板能力与 Karate 测试框架深度打通Feature 文件里的doc关键字即可渲染模板Scenario 的全部变量在模板中可用。Scenario: User report * def users [{name: Alice}, {name: Bob}] * doc user-report.html模板相对Feature 文件所在目录解析渲染出的 HTML 会内嵌进 HTML 测试报告。这使 Karate 既能驱动浏览器/API 测试又能直接产出可视化报告或邮件内容模板能力成为测试产物生成的一环。与标准 Thymeleaf 的差异速查最后TEMPLATING.md 明确列出了本引擎与标准 Thymeleaf 的五处差异是迁移或混用时的硬性边界表达式语言是 JavaScript而非 OGNL/SpEL用list.length、list[0]、真正的if/else。th:with用:赋值不是。迭代状态变量固定叫iter而非itemStatth:eachitem, iter: items。简单片段路径自动包~{}th:insertheader直接可用具名片段仍需~{header :: nav}显式语法。Map 自动转换为[{key, value}]供th:each迭代。总结一条从模板到全栈服务的完整链路至此Karate 模板引擎的全貌已经清晰以 Thymeleaf 属性语法为「形」以 JavaScript 为「神」以ka:*为「骨」将服务端脚本ka:scope、HTMXka:get/ka:post/ka:vals、Alpine.jska:data、SSE 推送、JS API Handler、Shell 布局、CSRF 防护与静态报告生成统一在一套渲染管线中。无论你是要用doc关键字从 Feature 生成报告还是用ServerConfig快速搭一个 HTMX Alpine 的全栈原型都可以从本文的配置表与代码示例直接起步并在 ServerConfig.java 与 markup 包 的处理器实现中验证每一个行为细节。赞分享测试接口测试性能测试Mock【免费下载链接】karateTest Automation Made Simple项目地址https://gitcode.com/gh_mirrors/ka/karate点击查看免费下载相关推荐Express 视图渲染与 EJS 模板引擎从服务端渲染到可复用模板的完整实战指南Express 视图渲染与 EJS 模板引擎从服务端渲染到可复用模板的完整实战指南 导读 本文围绕 Node.js/Express 应用中的视图层展开系文档教程教育Gutenberg Details 块core/details完全指南从 block.json 属性到服务端渲染增强Gutenberg Details 块core/details完全指南从 block.json 属性到服务端渲染增强 导读 Details 块是 Gute后端前端spring-boot-demo 集成 Thymeleaf 模板引擎实战指南从依赖引入到页面渲染spring boot demo 集成 Thymeleaf 模板引擎实战指南从依赖引入到页面渲染 本文以 spring boot demo 仓库中的 demo示例工程后端上一篇Calibre路径翻译终极解决方案彻底告别拼音路径困扰的完整指南下一篇Path of Building终极指南5步掌握流放之路最强Build规划工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考