AWS API Gateway Velocity转义字符问题：$esc.java()返回空值排查

我之前在处理API Gateway Velocity模板转义的时候也踩过类似的坑，来帮你拆解一下问题：

为什么$esc.java($element.name)会返回空？ #

可能有两个核心原因：

1. 字段本身不存在或为null
   先排查Lambda返回的JSON结构，确认每个$element里确实包含name字段。如果$element.name本身就是null或者未定义，哪怕用了转义函数，结果自然是空字符串。你可以先临时去掉转义，直接写"name": "$element.name"测试一下，如果输出还是空，那问题出在Lambda的返回数据上，和转义函数无关。

2. $esc.java()并非API Gateway Velocity环境支持的工具
   AWS API Gateway的Velocity模板有自己内置的工具类$util，而$esc.java()是标准Velocity框架里的工具，但API Gateway的模板环境可能并没有默认加载这个对象。官方文档里提到的转义方法，大概率是指$util下的转义函数，你可能看错了文档里的工具对象。

可行的解决方案 #

方案1：使用API Gateway内置的$util.escapeJavaScript() #

这是最推荐的方式，专门用来处理JSON/JavaScript字符串的转义，能正确处理双引号、反斜杠等特殊字符：

[
#foreach($element in $input.path('$.elements'))
  {
    "field1": "$element.field1",
    ...
    "name" : "$util.escapeJavaScript($element.name)",
    ...
  }#if($foreach.hasNext),#end
#end
]

方案2：手动用Velocity的replace方法转义 #

如果因为某些原因$util.escapeJavaScript()不生效，你可以手动处理常见的特殊字符：

"name" : "$element.name.replace('"', '\\"').replace('\\', '\\\\').replace('\n', '\\n').replace('\r', '\\r')"

这种方式需要你覆盖所有可能破坏JSON格式的字符，比如换行、回车等，适合特殊场景下的自定义转义。

方案3：让Lambda返回预转义的字段 #

如果你的业务允许，可以在Lambda里提前把name字段转义好再返回，这样API Gateway的模板就不需要做转义处理，直接输出即可。比如在Python里用json.dumps()处理字符串，Java里用StringEscapeUtils等工具类。

内容的提问来源于stack exchange，提问作者ldepablo