HttpHeaders
HttpHeaders 是用于存儲和操作HTTP請求或響應頭部字段的接口。
// DefaultHttpHeaders, HttpHeadersFactory.TrailingHttpHeaders
public interface HttpHeaders extends Iterable<Entry<CharSequence, CharSequence>> {static HttpHeaders emptyHeaders() {return newHeaders(2, true, true, true);}static HttpHeaders newHeaders() {return newHeaders(true);}static HttpHeaders newHeaders(boolean validate) {return newHeaders(16, validate, validate, validate);}static HttpHeaders newHeaders(int sizeHint, boolean checkNames, boolean checkCookies, boolean checkValues) {return new DefaultHttpHeaders(sizeHint, checkNames, checkCookies, checkValues);}HttpHeaders copy();@NullableCharSequence get(CharSequence name);default CharSequence get(final CharSequence name, final CharSequence defaultValue) {final CharSequence value = get(name);return value != null ? value : defaultValue;}@NullableCharSequence getAndRemove(CharSequence name);default CharSequence getAndRemove(final CharSequence name, final CharSequence defaultValue) {final CharSequence value = getAndRemove(name);return value == null ? defaultValue : value;}Iterator<CharSequence> valuesIterator(CharSequence name);default Iterable<CharSequence> values(CharSequence name) {return () -> (Iterator<CharSequence>) valuesIterator(name);}default boolean contains(final CharSequence name) {return get(name) != null;}default boolean contains(CharSequence name, CharSequence value) {return AsciiString.contentEquals(get(name), value);}default boolean containsIgnoreCase(CharSequence name, CharSequence value) {return AsciiString.contentEqualsIgnoreCase(get(name), value);}int size();default boolean isEmpty() {return size() == 0;}Set<CharSequence> names();HttpHeaders add(CharSequence name, CharSequence value);HttpHeaders add(CharSequence name, Iterable<? extends CharSequence> values);default HttpHeaders add(CharSequence name, Iterator<? extends CharSequence> valuesItr) {while (valuesItr.hasNext()) {add(name, valuesItr.next());}return this;}HttpHeaders add(CharSequence name, CharSequence... values);HttpHeaders add(HttpHeaders headers);HttpHeaders set(CharSequence name, CharSequence value);HttpHeaders set(CharSequence name, Iterable<? extends CharSequence> values);default HttpHeaders set(CharSequence name, Iterator<? extends CharSequence> valueItr) {remove(name);while (valueItr.hasNext()) {add(name, valueItr.next());}return this;}default HttpHeaders set(CharSequence name, CharSequence... values) {remove(name);for (CharSequence value : values) {add(name, value);}return this;}default HttpHeaders set(final HttpHeaders headers) {if (headers != this) {clear();add(headers);}return this;}default HttpHeaders replace(final HttpHeaders headers) {if (headers != this) {for (final CharSequence key : headers.names()) {remove(key);}add(headers);}return this;}boolean remove(CharSequence name);boolean remove(CharSequence name, CharSequence value);boolean removeIgnoreCase(CharSequence name, CharSequence value);HttpHeaders clear();@OverrideIterator<Entry<CharSequence, CharSequence>> iterator();@Overridedefault Spliterator<Entry<CharSequence, CharSequence>> spliterator() {return Spliterators.spliterator(iterator(), size(), Spliterator.SIZED);}@OverrideString toString();default String toString(BiFunction<? super CharSequence, ? super CharSequence, CharSequence> filter) {return HeaderUtils.toString(this, filter);}@NullableHttpCookiePair getCookie(CharSequence name);@NullableHttpSetCookie getSetCookie(CharSequence name);default Iterable<HttpCookiePair> getCookies() {return () -> (Iterator<HttpCookiePair>) getCookiesIterator();}Iterator<HttpCookiePair> getCookiesIterator();default Iterable<HttpCookiePair> getCookies(CharSequence name) {return () -> (Iterator<HttpCookiePair>) getCookiesIterator(name);}Iterator<HttpCookiePair> getCookiesIterator(CharSequence name);default Iterable<HttpSetCookie> getSetCookies() {return () -> (Iterator<HttpSetCookie>) getSetCookiesIterator();}Iterator<HttpSetCookie> getSetCookiesIterator();default Iterable<HttpSetCookie> getSetCookies(CharSequence name) {return () -> (Iterator<HttpSetCookie>) getSetCookiesIterator(name);}Iterator<HttpSetCookie> getSetCookiesIterator(CharSequence name);default Iterable<HttpSetCookie> getSetCookies(CharSequence name, CharSequence domain, CharSequence path) {return () -> (Iterator<HttpSetCookie>) getSetCookiesIterator(name, domain, path);}Iterator<HttpSetCookie> getSetCookiesIterator(CharSequence name, CharSequence domain, CharSequence path);HttpHeaders addCookie(HttpCookiePair cookie);default HttpHeaders addCookie(final CharSequence name, final CharSequence value) {return addCookie(new DefaultHttpCookiePair(name, value));}HttpHeaders addSetCookie(HttpSetCookie cookie);default HttpHeaders addSetCookie(final CharSequence name, final CharSequence value) {return addSetCookie(new DefaultHttpSetCookie(name, value));}boolean removeCookies(CharSequence name);boolean removeSetCookies(CharSequence name);boolean removeSetCookies(CharSequence name, CharSequence domain, CharSequence path);
}
HttpCookiePair
HttpCookiePair 接口定義了 HTTP Cookie 鍵值對的結構，包括名稱、值、是否被雙引號包裹及其編碼表示, 格式如下：
- <cookie-name>=<cookie-value>
- <cookie-name>=“<cookie-value>”
// DefaultHttpCookiePair
public interface HttpCookiePair {CharSequence name();CharSequence value();boolean isWrapped();CharSequence encodedCookie();
}
HttpSetCookie
HttpSetCookie 接口擴展了 HttpCookiePair，表示一個完整的 Set-Cookie，包含域、路徑、生命周期、安全屬性、SameSite 策略等信息，支持編碼與過期計算。
Set-Cookie HTTP 頭的格式大致如下：
Set-Cookie: <cookie-name>=<cookie-value>; Expires=<date>; Max-Age=<seconds>; Domain=<domain>; Path=<path>; Secure; HttpOnly; SameSite=<Lax|Strict|None>; Partitioned
| 字段名 | 是否必填 | 值類型 | 說明 |
|---|---|---|---|
name=value | 是 | 字符串 | Cookie 的名稱和值，必須出現在首位。value 可包含特殊字符，建議進行 URL 編碼。 |
Expires=<date> | 否 | GMT 日期字符串 | 設定 Cookie 的過期時間，格式如 Wed, 09 Jun 2027 10:18:14 GMT。過期即被刪除。 |
Max-Age=<秒數> | 否 | 整數（秒） | 設置 Cookie 的生存時間（從當前起多少秒），優先級高于 Expires。 |
Domain=<domain> | 否 | 字符串 | 指定 Cookie 可被哪些域訪問，默認是當前域，不帶子域；設置 .example.com 可包括子域。 |
Path=<path> | 否 | 字符串 | 指定 Cookie 生效的路徑，默認是當前路徑及其子路徑。常用 / 表示全站有效。 |
Secure | 否 | 無值 | 表示僅在 HTTPS 連接中發送該 Cookie，保障傳輸安全。 |
HttpOnly | 否 | 無值 | 禁止通過 JavaScript 訪問該 Cookie，可防范 XSS 攻擊。 |
SameSite | 否 | Lax | Strict | None | 控制是否允許跨站點請求攜帶該 Cookie。 ? Strict: 嚴格禁止跨站請求? Lax: 允許部分（如 GET 跳轉）? None: 允許全部，需配合 Secure |
Partitioned | 否 | 無值 | 指示該 Cookie 為分區 Cookie（Partitioned Cookie）。必須與 Secure 和 SameSite=None 一起使用，僅部分瀏覽器支持。 |
// DefaultHttpSetCookie
public interface HttpSetCookie extends HttpCookiePair {@NullableCharSequence domain();@NullableCharSequence path();@NullableLong maxAge();@NullableCharSequence expires();@Nullabledefault Long expiresAsMaxAge() {CharSequence expires = expires();if (expires != null) {Date expiresDate = DateFormatter.parseHttpDate(expires);if (expiresDate != null) {long maxAgeMillis = expiresDate.getTime() - System.currentTimeMillis();return maxAgeMillis / 1000 + (maxAgeMillis % 1000 != 0 ? 1 : 0);}}return null;}@NullableSameSite sameSite();boolean isSecure();boolean isHttpOnly();CharSequence encodedSetCookie();enum SameSite {Lax, Strict, None}boolean isPartitioned();
}
HttpHeadersFactory
HttpHeadersFactory 是用于創建和配置 HTTP 頭部對象及其校驗行為的工廠接口。
// DefaultHttpHeadersFactory
public interface HttpHeadersFactory {HttpHeaders newHeaders();HttpHeaders newEmptyHeaders();int getSizeHint();boolean isValidatingNames();boolean isValidatingValues();boolean isValidatingCookies();
}
public final class DefaultHttpHeadersFactory implements HttpHeadersFactory {private static final int SIZE_HINT = 16;private static final DefaultHttpHeadersFactory FOR_HEADER =new DefaultHttpHeadersFactory(SIZE_HINT, true, true, true, false);private static final DefaultHttpHeadersFactory FOR_TRAILER =new DefaultHttpHeadersFactory(SIZE_HINT, true, true, true, true);private static final int MIN_SIZE_HINT = 2;// 用于提示內部數據結構（通常是哈希表）應該多大。private final int sizeHint;// 是否開啟 HTTP 頭名稱的合法性校驗（比如是否符合 RFC 規定的字符集等）。private final boolean validateNames;// 是否開啟 HTTP 頭的值的合法性校驗。private final boolean validateValues;// 是否在解析 Cookie 時對 Cookie 內容做合法性校驗（如格式、字符等）。private final boolean validateCookies;// 是否以“尾部頭”（trailer header）專用的規則進行名稱校驗。private final boolean validateAsTrailer;private DefaultHttpHeadersFactory(int sizeHint, boolean validateNames, boolean validateValues, boolean validateCookies, boolean validateAsTrailer) {this.sizeHint = Math.max(MIN_SIZE_HINT, sizeHint); this.validateNames = validateNames;this.validateValues = validateValues;this.validateCookies = validateCookies;this.validateAsTrailer = validateAsTrailer;}public static DefaultHttpHeadersFactory headersFactory() {return FOR_HEADER;}public static DefaultHttpHeadersFactory trailersFactory() {return FOR_TRAILER;}@Overridepublic HttpHeaders newHeaders() {if (validateAsTrailer) {return new TrailingHttpHeaders(sizeHint, validateNames, validateCookies, validateValues);}return HttpHeaders.newHeaders(sizeHint, validateNames, validateCookies, validateValues);}@Overridepublic HttpHeaders newEmptyHeaders() {if (validateAsTrailer) {return new TrailingHttpHeaders(MIN_SIZE_HINT, validateNames, validateCookies, validateValues);}return HttpHeaders.newHeaders(MIN_SIZE_HINT, validateNames, validateCookies, validateValues);}// ...private static final class TrailingHttpHeaders extends DefaultHttpHeaders {TrailingHttpHeaders(int arraySizeHint, boolean validateNames, boolean validateCookies, boolean validateValues) {super(arraySizeHint, validateNames, validateCookies, validateValues);}// 該類用于處理 HTTP 的 trailing headers —— 即 chunked 編碼中的最后一塊 trailer 部分。// RFC 7230 明確禁止 trailing headers 不能包含某些首部字段，如：Content-Length, Transfer-Encoding, Trailer@Overrideprotected CharSequence validateKey(@Nullable CharSequence name, boolean forAdd) {if (HttpHeaderNames.CONTENT_LENGTH.contentEqualsIgnoreCase(name)|| HttpHeaderNames.TRANSFER_ENCODING.contentEqualsIgnoreCase(name)|| HttpHeaderNames.TRAILER.contentEqualsIgnoreCase(name)) {throw new IllegalArgumentException("Prohibited trailing header: " + name);}return super.validateKey(name, forAdd);}}
}
擴展功能)
)
