Scalar.Aws.Lambda 的 HTTP API 事件模型Payload Format 2.0路由、Stage 与响应编码全解析【免费下载链接】scalarScalar is an open-source API platform: Modern REST API Client Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalar本指南深入讲解Scalar.Aws.Lambda集成包在 Amazon API GatewayHTTP APIpayload format 2.0下的请求事件模型覆盖{proxy}贪婪路由的解析规则、命名 Stage 的自动剥离机制、HTTP API 特有的 Header 语义以及响应体的 Base64 编码约定。读完你将能够正确配置 SAM 模板路由、理解 Stage 与RoutePrefix的联动逻辑并准确预判静态资产与 HTML 页面在 HTTP API 场景下的响应形态避免常见的中文乱码、路径 404 与缓存失效问题。支持范围只有 HTTP API Payload Format 2.0Scalar.Aws.Lambda是一个有明确边界的事件适配器它只支持Amazon API GatewayHTTP API及其payload format 2.0事件模型对应的 .NET 类型为Amazon.Lambda.APIGatewayEvents命名空间下的APIGatewayHttpApiV2ProxyRequest—— 入站请求APIGatewayHttpApiV2ProxyResponse—— 出站响应这一边界在 getting-started.md 与 limitations.md 中被反复强调REST APIpayload format 1.0即APIGatewayProxyRequest/APIGatewayProxyResponse、Application Load Balancer 目标组、Lambda Function URLs 均不在本版本支持之列。原因在于这些事件源的路径/路由参数解析、Header 形态与 Stage 处理差异过大官方路线图倾向于为它们提供专门适配器而非做 best-effort 兼容层。若你确实在 Lambda 中托管完整的 ASP.NET Core 应用经由Amazon.Lambda.AspNetCoreServer则应改用Scalar.AspNetCore包的MapScalarApiReference()。{proxy}贪婪路由一切请求的入口HTTP API 支持{proxy}贪婪路径参数其语义与 ASP.NET Core 的 catch-all 路由参数{**rest}一类类似。Scalar.Aws.Lambda直接从request.PathParameters[proxy]读取路径剩余部分无需额外解析逻辑。在 SAM 模板中典型声明如下取自 http-api-model.md 的原始示例Events: ScalarIndex: Type: HttpApi Properties: Path: /scalar Method: GET ScalarProxy: Type: HttpApi Properties: Path: /scalar/{proxy} Method: ANY两条事件规则分工明确请求行为GET /scalar、GET /scalar/渲染默认文档openapi/v1.json的引用首页GET /scalar/v3渲染名为v3的文档openapi/v3.json的引用页GET /scalar/scalar.js、GET /scalar/scalar.aws.lambda.js、GET /scalar/favicon.svg返回内嵌静态资源源码中路由剩余部分的提取逻辑与文档完全对应见 ScalarApiReference.csprivate const string RouteRemainderKey proxy; private static string? GetRouteRemainder(APIGatewayHttpApiV2ProxyRequest request) { return request.PathParameters is not null request.PathParameters.TryGetValue(RouteRemainderKey, out var value) ? value : null; }关键兜底无PathParameters时不抛异常当PathParameters完全缺失时——典型场景是函数被直接调用例如控制台测试、定时器触发没有经过 API Gateway 的代理转发——GetRouteRemainder返回null请求会被安全地当作索引请求index request处理而不是抛出KeyNotFoundException之类的异常。这一点由 ScalarApiReference.cs 中request.RawPath ?? /与GetRouteRemainder的 null 容忍共同保证也让本地直接调用函数进行冒烟测试成为可能。路由参数名必须是proxy注意 limitations.md 中的硬性约定贪婪参数必须命名为proxy即Path: /scalar/{proxy}。适配器只读取request.PathParameters[proxy]这一个键用它来区分静态资源请求与引用页面请求并解析文档名。改名为其他任何值都会导致路由剩余部分永远解析不到。Stage 处理命名 Stage 的自动剥离HTTP API 与 REST API 在 URL 形态上有一个显著差异对于任何命名 StageStage 名会作为路径段嵌入RawPath唯独$defaultStage 不会。Scalar.Aws.Lambda利用这一特性做自动处理StageGET /scalar/的RawPath行为$default/scalar/不剥离任何前缀prod/prod/scalar/自动检测并剥离prod使相对 URL 不再携带 Stage 段其实现位于 ScalarApiReference.cs 的ApplyRoutePrefix方法private static void ApplyRoutePrefix(ScalarOptions options, APIGatewayHttpApiV2ProxyRequest request) { if (options.RoutePrefix is not null) { return; } var stage request.RequestContext?.Stage; if (!string.IsNullOrEmpty(stage) !string.Equals(stage, DefaultStageName, StringComparison.Ordinal)) { options.RoutePrefix stage; } }逻辑要点读取request.RequestContext.Stage若用户已经显式设置过ScalarOptions.RoutePrefix则完全跳过自动检测显式优先否则只要 Stage 非空且不是$default就把 Stage 名折叠进RoutePrefix用于后续解析相对 URL。这种做法与 Azure Functions 集成如出一辙——后者会把host.json中routePrefix配置的 HTTP 路由前缀折入同一个RoutePrefix选项两个集成在相对 URL 解析上保持了行为一致性。RoutePrefix选项的完整语义可参见 ScalarOptions.AwsLambda.cs默认值为null表示从RequestContext.Stage自动检测显式赋值后不再自动检测。测试 ScalarApiReferenceHandlerTests.cs 验证了命名 Stage 的剥离行为请求/prod/scalar/stage 为prod时渲染出的 HTML 中包含%2Fscalar%2F而不包含%2Fprod%2Fscalar%2F即 Stage 段不会泄漏进页面相对路径。自定义域名 Base Path需要显式配置一个容易踩坑的场景是自定义域名的基础路径映射base path mapping。这类映射会为 URL 增加一个前缀但这个前缀不会反映在RequestContext.Stage中——因为 API Gateway 在转发给 Lambda 之前已经剥离了自定义域名相关的 base path取决于配置方式。此时自动检测完全失效必须显式设置options.RoutePrefix my-base-path;相关约束同时记录在 limitations.md 的 Custom domain base path mappings 一节。无尾斜杠的 302 重定向当请求路径恰好等于路由前缀但缺少尾斜杠时如GET /scalar处理器返回 302 并重定向到scalar/以保证相对资源 URL 能正确解析。这一行为有测试覆盖ScalarRequestProcessorTests.cs 断言Status 302、RedirectLocation scalar/。Headers 语义小写化、逗号合并与大小写不敏感读取HTTP API 与 REST API 的 Header 形态存在本质差异适配器对此做了专门处理Header 名被小写化API Gateway HTTP API 会在headers字段中把 Header 名统一转为小写重复 Header 用逗号合并多个同名 Header 会被拼接成单个以逗号分隔的值没有multiValueHeaders字段这是 payload format 1.0REST API才有的字段format 2.0 中不存在。Scalar.Aws.Lambda读取Accept-Encoding与If-None-Match时采用大小写不敏感匹配见 ScalarApiReference.csprivate static bool AcceptsGzip(IDictionarystring, string? headers) { var value GetHeader(headers, accept-encoding); return value is not null value.Contains(gzip, StringComparison.OrdinalIgnoreCase); } private static string? GetHeader(IDictionarystring, string? headers, string name) { if (headers is null) { return null; } foreach (var (key, value) in headers) { if (string.Equals(key, name, StringComparison.OrdinalIgnoreCase)) { return value; } } return null; }这样做的实际价值在于虽然 API Gateway 通常会小写化 Header 名但直接的测试调用本地调试、控制台 Invoke可能保留调用方原始大小写。大小写不敏感遍历保证两种场景行为一致gzip 内容协商Accept-Encoding含gzip与条件请求If-None-Match命中 ETag 时返回 304在任何调用方式下都可靠。响应体编码IsBase64Encoded的精确语义APIGatewayHttpApiV2ProxyResponse.IsBase64Encoded是一个二元开关Scalar.Aws.Lambda对它的设置遵循严格规则true仅当响应体是gzip 压缩的静态资源二进制内容时设置。此时响应还会带上Content-Encoding: gzipHeaderBody 被Convert.ToBase64String编码为 Base64 字符串——这是 API Gateway 与 Lambda 响应契约对二进制 body 的硬性要求falseHTML 页面与未压缩的静态资源一律以纯 UTF-8 文本返回Body 直接写原始字符串不做 Base64 编码。实现位于 ScalarApiReference.cs 的BuildResponseAsyncif (result.Html is not null) { response.Body result.Html; response.IsBase64Encoded false; } else if (result.AssetStream is not null) { // ... if (result.ContentEncoding is not null) { // The stream holds gzip-compressed binary content... response.Headers[Content-Encoding] result.ContentEncoding; response.Body Convert.ToBase64String(bytes); response.IsBase64Encoded true; } else { response.Body Encoding.UTF8.GetString(bytes); response.IsBase64Encoded false; } }这一约定与测试互相印证ScalarRequestProcessorTests.cs 验证静态资源在启用 gzip 时返回Cache-Control: no-cache并设置Vary: Accept-EncodingScalarApiReferenceHandlerTests.cs 则断言静态工厂与 DI 两条入口对同一输入产生完全一致的StatusCode、Body与IsBase64Encoded。附状态码与缓存相关行为速查结合上述源码与测试Scalar.Aws.Lambda的输出状态码体系可归纳为状态码触发条件200正常渲染 HTML 引用页或返回静态资源302索引请求缺少尾斜杠重定向到scalar/304If-None-Match与资源 ETag 匹配条件请求未修改404处理器判定资源不存在静态资源带有 ETag 与缓存头未启用 gzip 时Cache-Control视资源类型而定测试中 gzip 场景为no-cache并输出Vary: Accept-EncodingHTML 页面在配置 Nonce/DynamicNonce 时使用Cache-Control: no-store见 ScalarRequestProcessorTests.cs。进一步阅读上手配置与两种入口零 DI 静态工厂 / DI 注册getting-started.md支持边界与路线图limitations.md入口实现ScalarApiReferenceHandler.cs请求处理核心ScalarApiReference.cs路由前缀选项ScalarOptions.AwsLambda.cs行为验证测试ScalarRequestProcessorTests.cs、ScalarApiReferenceHandlerTests.cs【免费下载链接】scalarScalar is an open-source API platform: Modern REST API Client Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalar创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Scalar.Aws.Lambda 的 HTTP API 事件模型（Payload Format 2.0）：路由、Stage 与响应编码全解析
Scalar.Aws.Lambda 的 HTTP API 事件模型Payload Format 2.0路由、Stage 与响应编码全解析【免费下载链接】scalarScalar is an open-source API platform: Modern REST API Client Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalar本指南深入讲解Scalar.Aws.Lambda集成包在 Amazon API GatewayHTTP APIpayload format 2.0下的请求事件模型覆盖{proxy}贪婪路由的解析规则、命名 Stage 的自动剥离机制、HTTP API 特有的 Header 语义以及响应体的 Base64 编码约定。读完你将能够正确配置 SAM 模板路由、理解 Stage 与RoutePrefix的联动逻辑并准确预判静态资产与 HTML 页面在 HTTP API 场景下的响应形态避免常见的中文乱码、路径 404 与缓存失效问题。支持范围只有 HTTP API Payload Format 2.0Scalar.Aws.Lambda是一个有明确边界的事件适配器它只支持Amazon API GatewayHTTP API及其payload format 2.0事件模型对应的 .NET 类型为Amazon.Lambda.APIGatewayEvents命名空间下的APIGatewayHttpApiV2ProxyRequest—— 入站请求APIGatewayHttpApiV2ProxyResponse—— 出站响应这一边界在 getting-started.md 与 limitations.md 中被反复强调REST APIpayload format 1.0即APIGatewayProxyRequest/APIGatewayProxyResponse、Application Load Balancer 目标组、Lambda Function URLs 均不在本版本支持之列。原因在于这些事件源的路径/路由参数解析、Header 形态与 Stage 处理差异过大官方路线图倾向于为它们提供专门适配器而非做 best-effort 兼容层。若你确实在 Lambda 中托管完整的 ASP.NET Core 应用经由Amazon.Lambda.AspNetCoreServer则应改用Scalar.AspNetCore包的MapScalarApiReference()。{proxy}贪婪路由一切请求的入口HTTP API 支持{proxy}贪婪路径参数其语义与 ASP.NET Core 的 catch-all 路由参数{**rest}一类类似。Scalar.Aws.Lambda直接从request.PathParameters[proxy]读取路径剩余部分无需额外解析逻辑。在 SAM 模板中典型声明如下取自 http-api-model.md 的原始示例Events: ScalarIndex: Type: HttpApi Properties: Path: /scalar Method: GET ScalarProxy: Type: HttpApi Properties: Path: /scalar/{proxy} Method: ANY两条事件规则分工明确请求行为GET /scalar、GET /scalar/渲染默认文档openapi/v1.json的引用首页GET /scalar/v3渲染名为v3的文档openapi/v3.json的引用页GET /scalar/scalar.js、GET /scalar/scalar.aws.lambda.js、GET /scalar/favicon.svg返回内嵌静态资源源码中路由剩余部分的提取逻辑与文档完全对应见 ScalarApiReference.csprivate const string RouteRemainderKey proxy; private static string? GetRouteRemainder(APIGatewayHttpApiV2ProxyRequest request) { return request.PathParameters is not null request.PathParameters.TryGetValue(RouteRemainderKey, out var value) ? value : null; }关键兜底无PathParameters时不抛异常当PathParameters完全缺失时——典型场景是函数被直接调用例如控制台测试、定时器触发没有经过 API Gateway 的代理转发——GetRouteRemainder返回null请求会被安全地当作索引请求index request处理而不是抛出KeyNotFoundException之类的异常。这一点由 ScalarApiReference.cs 中request.RawPath ?? /与GetRouteRemainder的 null 容忍共同保证也让本地直接调用函数进行冒烟测试成为可能。路由参数名必须是proxy注意 limitations.md 中的硬性约定贪婪参数必须命名为proxy即Path: /scalar/{proxy}。适配器只读取request.PathParameters[proxy]这一个键用它来区分静态资源请求与引用页面请求并解析文档名。改名为其他任何值都会导致路由剩余部分永远解析不到。Stage 处理命名 Stage 的自动剥离HTTP API 与 REST API 在 URL 形态上有一个显著差异对于任何命名 StageStage 名会作为路径段嵌入RawPath唯独$defaultStage 不会。Scalar.Aws.Lambda利用这一特性做自动处理StageGET /scalar/的RawPath行为$default/scalar/不剥离任何前缀prod/prod/scalar/自动检测并剥离prod使相对 URL 不再携带 Stage 段其实现位于 ScalarApiReference.cs 的ApplyRoutePrefix方法private static void ApplyRoutePrefix(ScalarOptions options, APIGatewayHttpApiV2ProxyRequest request) { if (options.RoutePrefix is not null) { return; } var stage request.RequestContext?.Stage; if (!string.IsNullOrEmpty(stage) !string.Equals(stage, DefaultStageName, StringComparison.Ordinal)) { options.RoutePrefix stage; } }逻辑要点读取request.RequestContext.Stage若用户已经显式设置过ScalarOptions.RoutePrefix则完全跳过自动检测显式优先否则只要 Stage 非空且不是$default就把 Stage 名折叠进RoutePrefix用于后续解析相对 URL。这种做法与 Azure Functions 集成如出一辙——后者会把host.json中routePrefix配置的 HTTP 路由前缀折入同一个RoutePrefix选项两个集成在相对 URL 解析上保持了行为一致性。RoutePrefix选项的完整语义可参见 ScalarOptions.AwsLambda.cs默认值为null表示从RequestContext.Stage自动检测显式赋值后不再自动检测。测试 ScalarApiReferenceHandlerTests.cs 验证了命名 Stage 的剥离行为请求/prod/scalar/stage 为prod时渲染出的 HTML 中包含%2Fscalar%2F而不包含%2Fprod%2Fscalar%2F即 Stage 段不会泄漏进页面相对路径。自定义域名 Base Path需要显式配置一个容易踩坑的场景是自定义域名的基础路径映射base path mapping。这类映射会为 URL 增加一个前缀但这个前缀不会反映在RequestContext.Stage中——因为 API Gateway 在转发给 Lambda 之前已经剥离了自定义域名相关的 base path取决于配置方式。此时自动检测完全失效必须显式设置options.RoutePrefix my-base-path;相关约束同时记录在 limitations.md 的 Custom domain base path mappings 一节。无尾斜杠的 302 重定向当请求路径恰好等于路由前缀但缺少尾斜杠时如GET /scalar处理器返回 302 并重定向到scalar/以保证相对资源 URL 能正确解析。这一行为有测试覆盖ScalarRequestProcessorTests.cs 断言Status 302、RedirectLocation scalar/。Headers 语义小写化、逗号合并与大小写不敏感读取HTTP API 与 REST API 的 Header 形态存在本质差异适配器对此做了专门处理Header 名被小写化API Gateway HTTP API 会在headers字段中把 Header 名统一转为小写重复 Header 用逗号合并多个同名 Header 会被拼接成单个以逗号分隔的值没有multiValueHeaders字段这是 payload format 1.0REST API才有的字段format 2.0 中不存在。Scalar.Aws.Lambda读取Accept-Encoding与If-None-Match时采用大小写不敏感匹配见 ScalarApiReference.csprivate static bool AcceptsGzip(IDictionarystring, string? headers) { var value GetHeader(headers, accept-encoding); return value is not null value.Contains(gzip, StringComparison.OrdinalIgnoreCase); } private static string? GetHeader(IDictionarystring, string? headers, string name) { if (headers is null) { return null; } foreach (var (key, value) in headers) { if (string.Equals(key, name, StringComparison.OrdinalIgnoreCase)) { return value; } } return null; }这样做的实际价值在于虽然 API Gateway 通常会小写化 Header 名但直接的测试调用本地调试、控制台 Invoke可能保留调用方原始大小写。大小写不敏感遍历保证两种场景行为一致gzip 内容协商Accept-Encoding含gzip与条件请求If-None-Match命中 ETag 时返回 304在任何调用方式下都可靠。响应体编码IsBase64Encoded的精确语义APIGatewayHttpApiV2ProxyResponse.IsBase64Encoded是一个二元开关Scalar.Aws.Lambda对它的设置遵循严格规则true仅当响应体是gzip 压缩的静态资源二进制内容时设置。此时响应还会带上Content-Encoding: gzipHeaderBody 被Convert.ToBase64String编码为 Base64 字符串——这是 API Gateway 与 Lambda 响应契约对二进制 body 的硬性要求falseHTML 页面与未压缩的静态资源一律以纯 UTF-8 文本返回Body 直接写原始字符串不做 Base64 编码。实现位于 ScalarApiReference.cs 的BuildResponseAsyncif (result.Html is not null) { response.Body result.Html; response.IsBase64Encoded false; } else if (result.AssetStream is not null) { // ... if (result.ContentEncoding is not null) { // The stream holds gzip-compressed binary content... response.Headers[Content-Encoding] result.ContentEncoding; response.Body Convert.ToBase64String(bytes); response.IsBase64Encoded true; } else { response.Body Encoding.UTF8.GetString(bytes); response.IsBase64Encoded false; } }这一约定与测试互相印证ScalarRequestProcessorTests.cs 验证静态资源在启用 gzip 时返回Cache-Control: no-cache并设置Vary: Accept-EncodingScalarApiReferenceHandlerTests.cs 则断言静态工厂与 DI 两条入口对同一输入产生完全一致的StatusCode、Body与IsBase64Encoded。附状态码与缓存相关行为速查结合上述源码与测试Scalar.Aws.Lambda的输出状态码体系可归纳为状态码触发条件200正常渲染 HTML 引用页或返回静态资源302索引请求缺少尾斜杠重定向到scalar/304If-None-Match与资源 ETag 匹配条件请求未修改404处理器判定资源不存在静态资源带有 ETag 与缓存头未启用 gzip 时Cache-Control视资源类型而定测试中 gzip 场景为no-cache并输出Vary: Accept-EncodingHTML 页面在配置 Nonce/DynamicNonce 时使用Cache-Control: no-store见 ScalarRequestProcessorTests.cs。进一步阅读上手配置与两种入口零 DI 静态工厂 / DI 注册getting-started.md支持边界与路线图limitations.md入口实现ScalarApiReferenceHandler.cs请求处理核心ScalarApiReference.cs路由前缀选项ScalarOptions.AwsLambda.cs行为验证测试ScalarRequestProcessorTests.cs、ScalarApiReferenceHandlerTests.cs【免费下载链接】scalarScalar is an open-source API platform: Modern REST API Client Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalar创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考