jquick-curl

jquick-curl

English | 简体中文

jquick-curl is a lightweight HTTP client for Java that natively mimics the curl style API: you write a request as a plain curl command and call it as an ordinary Java method. Commands are parsed with ANTLR and executed over a pooled, high-performance transport layer, so there is no hand-written request building code. jquick-curl is a sub-project of the JQuick ecosystem and is maintained by the Dromara open-source community.

⭐ This project is included in the Awesome Java list.

Features

• Native curl style API — describe a request with a curl command, call it with a Java method.
• Annotation and XML configuration — declare requests with @JCurlCommand or centralize them in apis.xml.
• Dynamic proxy clients — JCurlInvoker.createProxy(UserApi.class) turns an interface into a working client.
• Variable substitution — resolve ${name} / #{name} placeholders from the request at runtime.
• Conditional rendering — render headers or options only when an XML `` expression is true.
• Cookie support — manual cookies, a file-backed cookie jar, and Set-Cookie persistence.
• HTTP methods — GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, TRACE.
• File transfer — multipart upload with -F and download with -o / --output.
• Batch execution — run every @JCurlCommand method of a class in a single call.
• Timeouts, retries, redirects and connection pooling — configured once through JQuickCurlConfig.
• Interceptors — add authentication, logging or request preprocessing globally.
• Proxy and SSL — HTTP / SOCKS5 proxy, plus -k / --insecure to skip certificate checks.

Quick Start

1. Maven dependency

    io.github.paohaijiao
    jquick-curl
    2.5.0

2. Basic GET

Declare the curl command on an interface method, then create a proxy and call it.

import com.github.paohaijiao.anno.JCurlCommand;
import com.github.paohaijiao.domain.req.JQuickCurlReq;
import com.github.paohaijiao.executor.JCurlInvoker;

public interface UserApi {

    // GET request: returns the response body as a String
    @JCurlCommand("curl -X GET https://httpbin.org/get")
    String list(JQuickCurlReq request);
}

class GetDemo {
    public static void main(String[] args) throws Exception {
        UserApi api = JCurlInvoker.createProxy(UserApi.class);
        String body = api.list(new JQuickCurlReq());
        System.out.println(body);
    }
}

3. Basic POST

…

4. Cookie usage

jquick-curl implements the cookie options of native curl: -b / --cookie for sending cookies and -c / --cookie-jar for persisting them. Cookies are merged into a single Cookie request header, and every Set-Cookie header can be saved to a Netscape cookie file that plays the role of a persistent cookie store.

4.1 Set a single cookie manually

…

4.2 Set multiple cookies manually

public interface CookieApi {

    // Multiple cookies: separate them with a semicolon inside one -b option
    @JCurlCommand("curl -X GET https://httpbin.org/cookies " +
            "-b 'sessionId=abc123; theme=dark; lang=en'")
    String withMultipleCookies(JQuickCurlReq request);

    // Equivalent form: set the Cookie header directly with -H
    @JCurlCommand("curl -X GET https://httpbin.org/cookies " +
            "-H 'Cookie: sessionId=abc123; theme=dark; lang=en'")
    String withCookieHeader(JQuickCurlReq request);
}

Multiple cookies are separated by ;. Both -b and -H 'Cookie: ...' end up in the same Cookie request header, and repeated names are merged instead of overwritten.

4.3 Carry cookies automatically from a cookie jar file

public interface CookieApi {

    // Load cookies from a Netscape / Mozilla cookie file: -b @file
    @JCurlCommand("curl -X GET https://httpbin.org/cookies -b @./cookies.txt")
    String withJarFile(JQuickCurlReq request);
}

-b @cookies.txt reads a Netscape format cookie file and attaches the cookies to the request automatically, which is how jquick-curl keeps cookies across calls. Note the @ prefix before the file name.

4.4 Read Set-Cookie from the response

Return JQuickCurlResponseBody instead of String when you need response headers.

…

4.5 Persist cookies and reuse the session

…

-c / --cookie-jar writes every Set-Cookie header to the given file in Netscape format (seven tab-separated columns), and -b @file reuses it on later requests, which keeps a login session alive across calls. Never commit a real cookie file to a repository.

More Examples

XML configuration

Centralize API definitions in XML so request templates stay out of Java code.

    
        curl -X GET https://api.example.com/users/#{id} -b @./cookies.txt
    

…

The `` attribute must match the Java method name, and #{name} is the placeholder used by XML proxies.

Variable substitution and conditional rendering

public interface AuthApi {

    // ${...} placeholders are resolved from JQuickCurlReq
    @JCurlCommand("curl -X GET https://api.example.com/me -u ${user}:${password}")
    String currentUser(JQuickCurlReq request);
}

JQuickCurlReq request = new JQuickCurlReq();
request.put("user", "ada");
request.put("password", System.getenv("API_PASSWORD"));
String me = JCurlInvoker.createProxy(AuthApi.class).currentUser(request);

    curl -X GET #{host}/search
     -H "X-Trace: #{traceId}" 

${...} is used by annotation proxies and #{...} by XML proxies. A header inside `` is appended only when the expression is true. Keep credentials in variables instead of hard-coding them in the command.

File upload and download

…

-F accepts several files and can mix them with regular form fields. --output writes the response to disk inside the executor; alternatively declare a byte[] return type and save the bytes in your own code.

Batch execution

…

Batch execution scans every public method annotated with @JCurlCommand and invokes them in order.

Timeouts, connection pool and interceptors

import com.github.paohaijiao.config.JQuickCurlConfig;
import okhttp3.Interceptor;

import java.util.concurrent.TimeUnit;

JQuickCurlConfig.getInstance()
        .connectTimeout(3, TimeUnit.SECONDS)
        .readTimeout(10, TimeUnit.SECONDS)
        .writeTimeout(10, TimeUnit.SECONDS)
        .connectionPool(50, 5, TimeUnit.MINUTES)
        .maxRetryCount(2)
        .followRedirects(true);

// Add a global interceptor, for example a Bearer token
Interceptor auth = chain -> chain.proceed(
        chain.request().newBuilder()
                .addHeader("Authorization", "Bearer " + System.getenv("API_TOKEN"))
                .build());

JQuickCurlConfig.getInstance().addInterceptor(auth);

JQuickCurlConfig is a global singleton that manages timeouts, the connection pool, retries, redirects and interceptors. A single method can override its timeouts with @JTimeout.

Implemented curl options

The options above are covered by the parser and the test suite. Verify any unlisted curl option before relying on it.

Documentation

• apis.xml — XML API definition sample.
• Jquick-curl.dtd — DTD for the XML definition file.
• README-CN.md — Simplified Chinese documentation.
• Releases — version history and release notes.
• Issues — bug reports and feature requests.

Contributing

Contributions of any kind are welcome.

1. Read CONTRIBUTING-EN.md (or CONTRIBUTING.md) before making changes.
2. Include the version, environment, minimal reproduction and full error output when opening an issue.
3. Add or update tests before submitting a pull request, and keep each change focused.
4. Never commit secrets, tokens, personal data or production configuration.

License

jquick-curl is released under the Apache License 2.0. When using, modifying or distributing the project, comply with the license terms, including copyright, patent and notice requirements.