Java构建路径段全URL编码URI：GitLab API编码问题排查

问题背景 #

调用GitLab Repository File API时，要求文件路径作为URL路径段需完整URL编码（包括.要转为%2E），但使用RestTemplate时遇到以下问题：

• 直接传入已编码URL字符串会触发双重编码
• 使用UriComponentsBuilder默认构建时，.不会被编码
• 手动替换.为%2E后再构建，又会被双重编码

需要生成的正确URI路径段为：projects/13083/repository/files/app%2Fmodels%2Fkey%2Erb?ref=main

解决方案1：手动构造URI对象绕过自动编码 #

直接构建符合要求的URI字符串，通过new URI()创建对象传给RestTemplate，避免框架自动编码。

import java.net.URI;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
import org.springframework.web.client.RestTemplate;

public class GitLabApiClient {
    public static void main(String[] args) throws Exception {
        String rawFilePath = "app/models/key.rb";
        // 先编码路径中的/，再手动替换.为%2E
        String encodedFilePath = URLEncoder.encode(rawFilePath, StandardCharsets.UTF_8)
                .replace(".", "%2E");
        
        String fullUriStr = "https://your-gitlab-instance/api/v4/projects/13083/repository/files/" + encodedFilePath + "?ref=main";
        URI targetUri = new URI(fullUriStr);
        
        RestTemplate restTemplate = new RestTemplate();
        String apiResponse = restTemplate.getForObject(targetUri, String.class);
    }
}

解决方案2：自定义UriComponents编码逻辑 #

通过自定义编码规则强制处理.，再用UriComponentsBuilder构建URI，确保编码符合GitLab要求。

import java.net.URI;
import java.nio.charset.StandardCharsets;
import java.util.stream.Collectors;
import org.springframework.web.client.RestTemplate;
import org.springframework.web.util.UriComponentsBuilder;

public class GitLabApiClient {
    public static void main(String[] args) {
        String rawFilePath = "app/models/key.rb";
        // 自定义编码：对/和.进行URL编码
        String encodedFilePath = rawFilePath.chars()
                .mapToObj(c -> {
                    if (c == '/' || c == '.') {
                        return "%" + String.format("%02X", c);
                    }
                    return String.valueOf((char) c);
                })
                .collect(Collectors.joining());
        
        URI targetUri = UriComponentsBuilder.fromHttpUrl("https://your-gitlab-instance/api/v4/projects/13083/repository/files/{filePath}")
                .queryParam("ref", "main")
                .buildAndExpand(encodedFilePath)
                .encode(StandardCharsets.UTF_8)
                .build();
        
        RestTemplate restTemplate = new RestTemplate();
        String apiResponse = restTemplate.getForObject(targetUri, String.class);
    }
}

问题原因说明 #

1. 双重编码问题：RestTemplate默认会对传入的字符串URL进行编码，若提前编码会导致%被再次转为%25；
2. .未编码问题：标准URI编码规则中，.属于安全保留字符，默认不会被编码，但GitLab API要求对其进行编码；
3. 手动替换后双重编码：UriComponentsBuilder的encode()方法会对所有非标准字符编码，包括手动添加的%，导致%2E变为%252E。

内容的提问来源于stack exchange，提问作者marcell-janovszki