JSON:API Starter

受众：开发者 摘要：可选 JSON:API Resource Document 表示层。用于开放 API、第三方集成和 SDK 兼容接口，不替代现有 Result。

何时使用

场景	建议
对外开放 API 需要标准 resource document	使用 JSON:API starter 显式返回 JsonApiDocument
第三方同步接口需要 links / meta / included	使用 JsonApiResource、JsonApiRelationship 和 JsonApiLink
错误响应需要标准化 status / code / source	使用 JsonApiError
后台、App、PC 普通业务接口	继续使用现有 Result，不要全局替换

JSON:API starter 是可选表示层，不接管 Controller、不自动包裹返回值、不绑定 Entity / VO，也不替代 OpenAPI 文档能力。是否采用 JSON:API 应由具体开放接口显式选择。

快速开始

<dependency>
    <groupId>com.springopen</groupId>
    <artifactId>spring-open-starter-json-api</artifactId>
</dependency>

JsonApiResource article = JsonApiResource.builder("articles", articleId)
        .attribute("title", "Hello")
        .relationship("author", JsonApiRelationship.toOne(JsonApiResourceIdentifier.of("users", userId)))
        .link("self", "/api/v1/public/articles/" + articleId)
        .build();

return JsonApiDocument.resource(article)
        .withMeta("traceId", traceId);

也可以注入 JsonApiResourceAssembler：

JsonApiDocument<JsonApiResource> document = assembler.document(
        assembler.resource("articles", articleId)
                .attribute("title", "Hello")
                .build());

模型说明

类型	职责
JsonApiDocument<T>	Top-level document；约束 data 和 errors 不能同时存在
JsonApiResource	Resource object；包含 type、id、attributes、relationships、links、meta
JsonApiResourceIdentifier	Relationship data 中的轻量 resource identifier
JsonApiRelationship	to-one / to-many relationship
JsonApiLink	Link object，支持 link-level meta
JsonApiError	Error object，支持 status、code、title、detail、source、meta
JsonApiResourceAssembler	Spring Bean 形式的便捷工厂

错误响应

JsonApiError error = JsonApiError.builder("404", "article-not-found", "Article not found")
        .detail("No article with id " + id)
        .source("parameter", "id")
        .build();

return JsonApiDocument.errors(List.of(error));

边界

• 不全局替换 Result。
• 不自动转换 Entity / VO；业务模块自己决定 resource type、attributes 和 relationships。
• 不负责权限、分页查询、OpenAPI 文档或 HTTP 状态码选择。
• 与 spring-open-starter-openapi 可并用：OpenAPI 负责文档描述，JSON:API 负责运行时响应形状。

验证

./mvnw -pl spring-open-starters/spring-open-starter-json-api test -DskipITs -DskipFrontend -Dsurefire.failIfNoSpecifiedTests=false
git diff --check -- spring-open-starters/spring-open-starter-json-api docs/zh-CN/json-api.md