TypeSpec Java 客户端:用 responseHeadersAsModel 让无响应体的操作返回强类型响应头模型-开发者社区

TypeSpec Java 客户端:用 responseHeadersAsModel 让无响应体的操作返回强类型响应头模型

【免费下载链接】typespec项目地址: https://gitcode.com/GitHub_Trending/ty/typespec

本文介绍 @typespec/http-client-java 新增的responseHeadersAsModel客户端选项:如何让只有响应头、没有响应体的数据面操作(典型如HEAD操作)的便捷方法(convenience method)从返回void变为返回一个强类型的响应头模型。读完后,你将掌握该选项的启用方式与适用边界、误用时的诊断信息,以及从 TypeSpec 声明、emitter 校验、Java 代码生成模板到最终模型类构造的完整实现链路。

功能背景:无响应体操作的便捷方法只能返回 void

在 Azure SDK 风格的 Java 客户端中,每个数据面操作通常生成两类方法:

协议方法(protocol method):如getResourceMetadataWithResponse(RequestOptions),返回Response<Void>或Response<T>;
便捷方法(convenience method):去掉RequestOptions参数、直接返回响应体类型的方法,如getResourceMetadata()。

对于HEAD这类只有响应头、没有响应体的操作,响应体类型是Void,便捷方法只能返回void,操作方精心定义的响应头(如ETag、Last-Modified、自定义计数头)只能停留在 Javadoc 的表格里,调用方必须退回协议方法手动解析HttpHeaders。本次变更(见变更说明)为这类操作提供了按操作粒度的可选(opt-in)能力:便捷方法直接返回一个由响应头构建的强类型模型,且不做任何 JSON/XML 序列化——模型构造函数直接从HttpHeaders中取值。

启用方式与适用边界

该功能通过标准的@@clientOption装饰器按操作启用,并限定目标语言为java:

@@clientOption(ResponseHeaderOp.getResourceMetadata, "responseHeadersAsModel", true, "java");

选项语义如下:

维度	说明
取值	`true`(布尔值)
作用对象	单个操作(按操作粒度,不是客户端全局)
适用前提	操作有响应头、但没有响应体(如`HEAD`操作)
生效后行为	便捷方法返回生成的响应头模型(由响应头直接构建,不经过序列化),替代原来的`void`;协议方法仍返回`Response<Void>`
误用行为	对有响应体的操作使用,emitter 直接报告错误,生成失败

误用时的诊断定义在 emitter/src/lib.ts 中,诊断码为response-headers-as-model-with-body,严重级别为error,消息模板为:

Client option 'responseHeadersAsModel' cannot be used on operation 'getWidget', because it has a response body.

配套的诊断文档 diagnostics/response-headers-as-model-with-body.md 给出了正反示例:对带@body body: Widget的操作启用该选项是错误的;去掉 body、仅保留@statusCode与响应头后,同样的选项才是合法用法。

完整示例:一个 HEAD 操作的声明

仓库测试工程中的 tsp/response-headers.tsp 是该功能的参考实现,覆盖了若干关键细节:

import "@typespec/rest"; import "@azure-tools/typespec-client-generator-core"; using TypeSpec.Http; using Azure.ClientGenerator.Core; @service(#{ title: "ResponseHeaders" }) namespace TspTest.ResponseHeaders; model MetadataHeaders { @header("x-ms-meta") metadata?: string; } @route("/response-headers") interface ResponseHeaderOp { // HEAD 操作:有显著响应头但没有响应体。 // 通过 "responseHeadersAsModel" 客户端选项,让便捷方法返回 // 强类型响应头模型,而不是 "void"。 @route("/resource-metadata") @head getResourceMetadata(): { @statusCode statusCode: 200; // 常量头不会出现在生成的响应头模型中 @header("x-constant-header") constantHeader: "constant-value"; // 必填头,混合大小写头名 @header("ETag") eTag: string; // 必填头 @header("x-resource-count") resourceCount: int32; // 可选头,混合大小写头名 @header("Last-Modified") lastModified?: utcDateTime; ...MetadataHeaders; }; } @@clientOption(ResponseHeaderOp.getResourceMetadata, "responseHeadersAsModel", true, "java"); @@alternateType(MetadataHeaders.metadata, Record<string>, "java"); @@clientOption(MetadataHeaders.metadata, "collectionHeaderPrefix", "x-ms-meta-", "java");

这个示例展示了四类头在生成模型中的归宿:

常量头(constantHeader: "constant-value")——编译期即可知的值,从生成的响应头模型中省略;
简单类型头(ETag: string、x-resource-count: int32)——直接成为模型属性,并保留声明中的混合大小写;
可选头(lastModified?: utcDateTime)——生成后可为null的属性;
前缀头集合(x-ms-meta-前缀,经collectionHeaderPrefix选项 +@@alternateType映射为Record<string>/Map<String, String>)——聚合为一个 Map 属性。

生成的 Java 代码长什么样

响应头模型:无序列化,直接由 HttpHeaders 构造

生成的模型类 ResponseHeaderOpsGetResourceMetadataHeaders.java 是这个功能的核心产物,注意它的构造方式——唯一构造函数接收原始HttpHeaders,逐头取值并做类型转换,完全没有 JSON/XML 反序列化逻辑:

@Immutable public final class ResponseHeaderOpsGetResourceMetadataHeaders { @Generated private final String eTag; @Generated private final Integer resourceCount; @Generated private final DateTimeRfc1123 lastModified; @Generated private final Map<String, String> metadata; // HttpHeaders containing the raw property values. public ResponseHeaderOpsGetResourceMetadataHeaders(HttpHeaders rawHeaders) { this.eTag = rawHeaders.getValue(HttpHeaderName.ETAG); String resourceCount = rawHeaders.getValue(X_RESOURCE_COUNT); if (resourceCount != null) { this.resourceCount = Integer.parseInt(resourceCount); } else { this.resourceCount = null; } // ... lastModified 同理,用 DateTimeRfc1123 解析 // metadata: 遍历所有以 "x-ms-meta-" 开头的头,剥掉前缀放入 Map } @Generated public OffsetDateTime getLastModified() { if (this.lastModified == null) { return null; } return this.lastModified.getDateTime(); } @Generated public Map<String, String> getMetadata() { return this.metadata; } // getETag() / getResourceCount() 同理 }

可以确认几个行为细节:必填string头映射为String属性;int32头映射为Integer,头缺失时属性为null而非抛异常;utcDateTime头用DateTimeRfc1123解析,getter 对外暴露OffsetDateTime;前缀头集合通过大小写不敏感的前缀匹配聚合,且键名剥掉x-ms-meta-前缀(示例中X-Ms-Meta-key1/x-ms-meta-key2都归入同一个 Map)。

便捷方法与协议方法:一个换型,一个不变

异步客户端 ResponseHeadersAsyncClient.java 中,两个方法分工清晰:

// 协议方法:仍然返回 Response<Void>,未受选项影响 @Generated @ServiceMethod(returns = ReturnType.SINGLE) public Mono<Response<Void>> getResourceMetadataWithResponse(RequestOptions requestOptions) { return this.serviceClient.getResourceMetadataWithResponseAsync(requestOptions); } // 便捷方法:返回强类型头模型,内部就是"取协议响应头 -> 构造模型" @Generated @ServiceMethod(returns = ReturnType.SINGLE) public Mono<ResponseHeaderOpsGetResourceMetadataHeaders> getResourceMetadata() { // Generated convenience method for getResourceMetadataWithResponse RequestOptions requestOptions = new RequestOptions(); return getResourceMetadataWithResponse(requestOptions) .map(protocolMethodResponse -> new ResponseHeaderOpsGetResourceMetadataHeaders( protocolMethodResponse.getHeaders())); }

这正好对应变更说明中的承诺:便捷方法返回头模型、协议方法继续返回Response<Void>,协议层的响应头表格 Javadoc 仍保留在两个方法上。

源码实现链路

Emitter 侧:校验 + 打标

从源码结构看,emitter 在 emitter/src/code-model-builder.ts 构建每个操作的ConvenienceApi时读取该选项(约 L1057-L1073):

// opt-in: return significant response headers as a strongly-typed model from the convenience method const responseHeadersAsModel = getClientOptions(sdkMethod, "responseHeadersAsModel") as boolean | undefined; if (responseHeadersAsModel === true) { if (sdkMethod.response.type !== undefined) { // the model is built purely from response headers, hence the operation must not have a response body this.program.reportDiagnostic( createDiagnostic({ code: "response-headers-as-model-with-body", format: { operationName: operationName }, target: sdkMethod.__raw ?? NoTarget, }), ); } else { codeModelOperation.convenienceApi.responseHeadersAsModel = true; } }

判定条件很直白:只要sdkMethod.response.type存在(即操作有响应体类型)就报 error;否则在 code model 的convenienceApi上打标。该标志的声明位于 emitter/src/common/operation.ts 的ConvenienceApi上:

/** * Whether the convenience method returns the significant response headers as a strongly-typed model * (opt-in via the "responseHeadersAsModel" client option). Only applicable to>protected static boolean isResponseHeadersAsModel(ClientMethod method) { final IType bodyType = getConvenienceResponseBodyType(method); if (bodyType instanceof ClassType) { final ClientModel model = ClientModelUtil.getClientModel(((ClassType) bodyType).getName()); return model != null && model.isStronglyTypedHeader(); } return false; }

可以看到,生成器并不重新解析 emitter 选项,而是依赖 code model 中ClientModel的isStronglyTypedHeader()标记;据此走"由响应头构造模型"的便捷方法生成路径。标记的载体定义在 ConvenienceApi.java 中。

测试验证

测试 ResponseHeadersTests.java 用 mock HTTP 层直接构造响应头,验证了端到端行为:

HttpHeaders responseHeaders = new HttpHeaders().set(HttpHeaderName.ETAG, "\"0x8D9\"") .set(HttpHeaderName.fromString("x-resource-count"), "42") .set(HttpHeaderName.LAST_MODIFIED, "Mon, 26 Aug 2022 14:38:00 GMT") .set(HttpHeaderName.fromString("X-Ms-Meta-key1"), "value1") .set(HttpHeaderName.fromString("x-ms-meta-key2"), "value2"); ResponseHeaderOpsGetResourceMetadataHeaders headers = createClient(responseHeaders).getResourceMetadata(); // 便捷方法返回由响应头直接构建的强类型头模型(模型本身没有 JSON/XML 序列化) Assertions.assertEquals("\"0x8D9\"", headers.getETag()); Assertions.assertEquals(42, headers.getResourceCount()); Assertions.assertEquals(OffsetDateTime.of(2022, 8, 26, 14, 38, 0, 0, ZoneOffset.UTC), headers.getLastModified()); Assertions.assertEquals(Map.of("key1", "value1", "key2", "value2"), headers.getMetadata());

第二个用例testOptionalHeaderAbsent验证了可选头缺失时的行为:响应中没有Last-Modified时,headers.getLastModified()返回null而不是抛异常。测试中的注释也明确了设计意图:模型"本身没有 JSON/XML 序列化"。