Spring Data REST自定义Controller端点返回结果不一致问题

场景说明 #

我有一个Spring Data REST应用，已将实体暴露为REST端点。主实体为Listing，包含一组Item：

@Entity
@Data
@AllArgsConstructor
@RequiredArgsConstructor
public class Listing extends RepresentationModel<Listing> {
    
    @Id
    @GeneratedValue
    private Long id;

    private int type;
    private String name;
    private String description;
    
    // ...其他字段

    @JsonIgnore
    @OneToMany(mappedBy = "listing")
    private List<Item> items;
}


@Entity
@Data
@AllArgsConstructor
@RequiredArgsConstructor
public class Item extends RepresentationModel<Item> {
    
    @Id
    @GeneratedValue
    private Long id;

    private String title;
    private int quantity;
    private float price;
    // ...其他字段

    @ManyToOne
    @JoinColumn(name="listing_id")
    public Listing listing;

}

Spring Data Repository定义 #

每个实体都有对应的Spring Data Repository：

public interface ItemRepository extends CrudRepository<Item, Long> {
}

public interface ListingRepository extends CrudRepository<Listing, Long> {
}

问题现象 #

通过http://<IP>:<PORT>/listings获取所有Listing时，返回符合预期的HAL格式JSON，包含_links字段及相关链接。

但创建自定义Controller后：

@RestController
public class CustomController{

    @Autowired
    private ListingRepository repository;

    @GetMapping("/matches")
    public Iterable<Listing> getMatches() {
        Iterable<Listing> listings = repository.findAll();
        return listings;
    }

    // ...其他方法
}

调用http://<IP>:<PORT>/matches时，返回的JSON存在两处差异：

1. 链接字段为links而非_links；
2. links为空数组，同时还暴露了id字段。

如何让两个端点返回的结果保持一致？

注：在Listing实体中，我为items集合添加了@JsonIgnore注解，否则会出现Listing与Item互相引用导致的无限递归输出。

解决方案 #

要让自定义控制器返回和Spring Data REST自动生成端点一致的HAL格式，按以下步骤处理：

1. 使用Spring Data REST的资源转换器 #

Spring Data REST内部通过PersistentEntityResourceAssembler将实体转换为HAL格式资源。在自定义控制器中注入该转换器，手动完成实体转换：

@RestController
public class CustomController{

    @Autowired
    private ListingRepository repository;

    @Autowired
    private PersistentEntityResourceAssembler assembler;

    @GetMapping("/matches")
    public ResponseEntity<Iterable<PersistentEntityResource>> getMatches() {
        Iterable<Listing> listings = repository.findAll();
        Iterable<PersistentEntityResource> resources = StreamSupport.stream(listings.spliterator(), false)
                .map(assembler::toModel)
                .collect(Collectors.toList());
        return ResponseEntity.ok(resources);
    }
}

2. 确保Jackson支持HAL格式 #

Spring Boot项目通常会自动引入Spring HATEOAS和HAL相关依赖并完成配置。如果是手动配置，需添加Jackson的HAL模块：

@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Bean
    public Module halModule() {
        return new Jackson2HalModule();
    }
}

3. 隐藏ID字段 #

Spring Data REST默认会隐藏实体的id字段，使用PersistentEntityResourceAssembler转换时会自动处理这一逻辑，无需额外配置。如果直接返回实体，可在id字段上添加@JsonIgnore注解实现隐藏。

关键原因 #

• Spring Data REST自动生成的端点会通过PersistentEntityResourceAssembler处理实体，将RepresentationModel中的links转换为HAL格式的_links，同时自动生成self等资源链接。
• 直接返回实体集合时，Jackson默认只会序列化RepresentationModel的links字段为普通数组，不会转换为HAL格式，也不会自动生成资源链接。

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