Spring Boot HATEOAS添加link时抛出IllegalArgumentException异常

1. linkTo() 方法在匹配多路径模板时，无法自动适配带可选路径变量的场景：当路径变量（如tenantId）为null（因required=false）时，Spring HATEOAS 无法确定使用哪个路径模板，导致抛出找不到变量的异常。
2. 调用methodOn()时传入了xTenantId（@RequestHeader参数），该参数不属于路径变量，会干扰路径模板的解析逻辑。

方案一：基于当前请求URI构建链接（最简单可靠） #

直接复用当前请求的URI生成self链接，完全绕开路径模板匹配问题：

import org.springframework.web.servlet.support.ServletUriComponentsBuilder;
import org.springframework.hateoas.Link;

// 替换原linkTo相关代码
UriComponentsBuilder uriBuilder = ServletUriComponentsBuilder.fromCurrentRequest();
Link selfLink = Link.of(uriBuilder.build().toUriString()).withSelfRel();
roundTypeResponse.add(selfLink);

方案二：拆分多路径为独立控制器方法 #

将三个路径分别对应独立方法，让linkTo()能精准匹配路径模板：

// 无租户ID的路径
@GetMapping("/competitions/rounds/roundTypes")
public HttpEntity<RepresentationModel<RoundTypeResponse>> getRoundTypes(
        @RequestHeader(value="X-TENANT-ID") String xTenantId
) {
    return getRoundTypesInternal(null, null, null, null, xTenantId);
}

// 包含租户、组织、项目、赛事ID的路径
@GetMapping("/tenants/{tenantId}/orgs/{orgId}/programs/{programId}/competitions/{competitionId}/rounds/roundTypes")
public HttpEntity<RepresentationModel<RoundTypeResponse>> getRoundTypesWithCompetition(
        @PathVariable Integer tenantId,
        @PathVariable Integer orgId,
        @PathVariable Integer programId,
        @PathVariable UUID competitionId,
        @RequestHeader(value="X-TENANT-ID") String xTenantId
) {
    return getRoundTypesInternal(tenantId, orgId, programId, competitionId, xTenantId);
}

// 包含租户、组织、项目ID的路径
@GetMapping("/tenants/{tenantId}/orgs/{orgId}/programs/{programId}/rounds/roundTypes")
public HttpEntity<RepresentationModel<RoundTypeResponse>> getRoundTypesWithProgram(
        @PathVariable Integer tenantId,
        @PathVariable Integer orgId,
        @PathVariable Integer programId,
        @RequestHeader(value="X-TENANT-ID") String xTenantId
) {
    return getRoundTypesInternal(tenantId, orgId, programId, null, xTenantId);
}

// 公共业务逻辑抽离
private HttpEntity<RepresentationModel<RoundTypeResponse>> getRoundTypesInternal(
        Integer tenantId,
        Integer orgId,
        Integer programId,
        UUID competitionId,
        String xTenantId
) {
    log.info("Request received to get round types... ");
    Utils.compareTenantIds(xTenantId, tenantId);
    Round round = new Round();
    round.setTenantId(tenantId);
    round.setOrgId(orgId);
    round.setProgramId(programId);
    round.setCompetitionId(competitionId != null ? competitionId.toString() : null);
    List<RoundType> dbRoundTypes = competitionService.getRoundTypes(round);
    RoundTypes roundTypes = new RoundTypes(dbRoundTypes.size(), dbRoundTypes);
    RoundTypeResponse roundTypeResponse = new RoundTypeResponse();
    roundTypeResponse.setContent(roundTypes);
    
    // 根据参数匹配对应方法生成链接
    Link selfLink;
    if (tenantId == null) {
        selfLink = linkTo(methodOn(CompetitionController_V2.class).getRoundTypes(xTenantId)).withSelfRel();
    } else if (competitionId == null) {
        selfLink = linkTo(methodOn(CompetitionController_V2.class).getRoundTypesWithProgram(tenantId, orgId, programId, xTenantId)).withSelfRel();
    } else {
        selfLink = linkTo(methodOn(CompetitionController_V2.class).getRoundTypesWithCompetition(tenantId, orgId, programId, competitionId, xTenantId)).withSelfRel();
    }
    roundTypeResponse.add(selfLink);
    
    return new ResponseEntity<>(roundTypeResponse, HttpStatus.OK);
}

方案三：优化linkTo调用逻辑（适配原单方法结构） #

移除methodOn()中的请求头参数，并根据路径变量是否存在手动选择匹配逻辑：

// 移除xTenantId参数（链接不包含请求头），根据变量值选择路径
Link selfLink;
if (tenantId == null) {
    selfLink = linkTo(methodOn(CompetitionController_V2.class).getRoundTypes(null, null, null, null, xTenantId)).withSelfRel();
} else if (competitionId == null) {
    selfLink = linkTo(methodOn(CompetitionController_V2.class).getRoundTypes(tenantId, orgId, programId, null, xTenantId)).withSelfRel();
} else {
    selfLink = linkTo(methodOn(CompetitionController_V2.class).getRoundTypes(tenantId, orgId, programId, competitionId, xTenantId)).withSelfRel();
}
roundTypeResponse.add(selfLink);

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