Java使用HttpClient如何传递URL动态路径参数发起POST请求

接口指南给出的https POST api_site.io/users/$username/token是RESTful接口的通用占位符写法，实际可访问的请求URL模板为：
POST https://api_site.io/users/{username}/token
其中{username}为路径位置的动态参数，需要替换为实际值后才能成功匹配接口。

核心实现步骤 #

• 完成URL模板的占位符替换：将模板中的{username}替换为实际业务场景的用户名字符串，必须对替换的用户名内容做URL编码，避免用户名包含空格、特殊符号时出现路径解析错误
• 基于替换完成的完整URL，发起标准POST请求，按需补充请求头、请求体内容即可

常见实现方案 #

JDK原生无依赖实现（HttpURLConnection） #

无需引入第三方依赖，基础实现代码：

import java.net.HttpURLConnection;
import java.net.URI;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;

public class PostApiDemo {
    public static void main(String[] args) throws Exception {
        // 接口URL模板
        String urlTemplate = "https://api_site.io/users/{username}/token";
        // 需要传入的动态用户名
        String actualUsername = "业务场景下的实际用户名";
        // 替换占位符，对用户名做URL编码
        String realUrl = urlTemplate.replace(
                "{username}",
                URLEncoder.encode(actualUsername, StandardCharsets.UTF_8)
        );
        // 建立HTTP连接
        HttpURLConnection connection = (HttpURLConnection) URI.create(realUrl).toURL().openConnection();
        // 设置请求方法为POST
        connection.setRequestMethod("POST");
        // 开启请求输出能力（需传请求体时必须开启）
        connection.setDoOutput(true);
        // 按需配置请求头
        connection.setRequestProperty("Content-Type", "application/json");
        // 发起请求，后续可按需读取响应状态码、响应内容
        int responseCode = connection.getResponseCode();
    }
}

第三方HTTP客户端实现 #

如果项目已引入OkHttp、Apache HttpClient这类成熟HTTP客户端，核心逻辑与原生实现完全一致：先替换路径占位符构造完整URL，再调用客户端的POST方法发起请求即可，无需重复处理底层网络连接逻辑。
以OkHttp为例的简化实现：

// 构造替换完成的完整请求地址
String requestUrl = "https://api_site.io/users/"
        + URLEncoder.encode(actualUsername, StandardCharsets.UTF_8)
        + "/token";
// 构造POST请求（无请求体时传空内容即可）
Request request = new Request.Builder()
        .url(requestUrl)
        .post(RequestBody.create("", null))
        .build();
// 执行请求
Response response = okHttpClientInstance.newCall(request).execute();

常见踩坑点 #

• 不要错把路径参数当成查询参数拼在URL末尾（例如拼成https://api_site.io/users/token?username=xxx），这种结构和接口要求的路径格式不匹配，会触发404错误
• 替换占位符时不能省略URL编码步骤，未编码的特殊字符会导致URL路径解析异常，返回400、404类错误
• 替换完成后检查URL的斜杠结构，避免出现连续双斜杠、漏斜杠导致的路径匹配失败

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