Serverless Offline Velocity模板应用：请求响应模板编写完全手册

Serverless Offline是Serverless Framework生态中一个强大的本地开发工具，它能够模拟AWS Lambda和API Gateway环境，让开发者在本地就能测试和调试Serverless应用。其中Velocity模板支持是Serverless Offline最核心的功能之一，通过Velocity模板，开发者可以灵活定制API Gateway的请求和响应处理逻辑。

什么是Velocity模板？

Velocity模板是AWS API Gateway中用于数据转换的模板语言，它基于Apache Velocity引擎。在Serverless Offline中，Velocity模板能够让你在本地环境中完全模拟API Gateway的请求映射和响应映射功能。

Velocity模板核心语法详解

变量定义与引用

在Velocity模板中，使用#set指令定义变量，使用$符号引用变量：

#set($name = "John")
#set($age = 25)
Hello $name, you are $age years old!

条件判断语句

Velocity支持#if、#elseif、#else等条件判断：

#if($user.role == "admin")
  Welcome Administrator!
#elseif($user.role == "user")
  Welcome User!
#else
  Welcome Guest!
#end

循环遍历

使用#foreach指令可以遍历集合：

#foreach($item in $list)
  Item: $item
#end

请求模板配置实战

Serverless Offline提供了默认的请求模板文件[offline-default.req.vm](https://gitcode.com/gh_mirrors/se/serverless-offline/blob/4eb803cf304969c8b8282a9e9477c41655ccb093/src/events/http/templates/offline-default.req.vm?utm_source=gitcode_repo_files)，该模板定义了如何将HTTP请求转换为Lambda事件格式。

请求模板关键组件

• HTTP方法：$context.httpMethod获取请求方法
• 请求头：通过$input.params().header访问请求头信息
• 查询参数：使用$input.params().querystring获取URL参数
• 路径参数：$input.params().path获取路径变量

自定义请求模板

在serverless.yml中配置自定义请求模板：

functions:
  hello:
    handler: handler.hello
    events:
      - http:
          path: /hello
          method: get
          request:
            template:
              application/json: |
                {
                  "body": $input.json('$'),
                  "method": "$context.httpMethod"
                }

响应模板配置指南

响应模板用于将Lambda函数的返回值转换为HTTP响应格式。Serverless Offline支持完整的响应模板功能。

响应模板核心功能

• 状态码映射：根据Lambda响应设置HTTP状态码
• 响应头处理：动态设置响应头信息
• 数据格式转换：将JSON数据转换为其他格式

实用Velocity工具函数

Serverless Offline提供了丰富的工具函数，位于[VelocityContext.js](https://gitcode.com/gh_mirrors/se/serverless-offline/blob/4eb803cf304969c8b8282a9e9477c41655ccb093/src/events/http/lambda-events/VelocityContext.js?utm_source=gitcode_repo_files)中：

常用工具函数

• $util.escapeJavaScript()：字符串转义
• $util.base64Encode()：Base64编码
• $util.urlEncode()：URL编码
• $input.json()：JSON路径查询

高级Velocity模板技巧

模板嵌套与复用

通过宏定义实现模板复用：

#define($loop)
{
#foreach($key in $map.keySet())
  "$util.escapeJavaScript($key)": "$util.escapeJavaScript($map.get($key))"
  #if($foreach.hasNext),#end
#end
}
#end

错误处理与调试

在Velocity模板开发过程中，常见的调试技巧包括：

• 使用简单的模板开始测试
• 逐步添加复杂逻辑
• 利用Serverless Offline的详细日志输出

最佳实践总结

1. 模板设计原则：保持模板简洁，避免过度复杂的逻辑
2. 本地测试流程：先本地测试，再部署到AWS
3. 版本控制：将Velocity模板纳入版本管理
4. 文档维护：为自定义模板编写详细说明文档

通过掌握Serverless Offline的Velocity模板应用，开发者可以大大提高本地开发效率，减少云端调试时间，实现真正的快速迭代开发。