瀏覽器同源策略禁止 JavaScript 直接向不同網域(協定/域名/埠口任一不同)發起 AJAX 請求。常見解決方案:
Access-Control-Allow-Origin 標頭(推薦,需控制後端)
瀏覽器 (前端) 同源 Servlet 代理 目標 API (跨域)
│ │ │
├─ POST /cross/proxy ──►│ │
│ {requesturl, params} │ │
│ ├─ HTTP Client (GET/POST)─►│
│ │◄─ 回應資料 (JSON/XML) ──┤
│◄─ 回應資料 ────────────┤ │
│ │ │
/**
* 跨域代理客戶端封裝
* @param {Object} options - 請求選項
* @param {string} options.targetUrl - 目標 API 完整 URL
* @param {string} [options.method='GET'] - HTTP 方法
* @param {Object} [options.params={}] - 查詢參數或請求體
* @param {Object} [options.headers={}] - 額外請求標頭
* @param {number} [options.timeout=30000] - 超時毫秒
* @returns {Promise} 解析為目標 API 回應資料
*/
function crossDomainRequest(options) {
var defaults = {
method: 'GET',
params: {},
headers: {},
timeout: 30000
};
var opts = $.extend(true, {}, defaults, options);
// 組裝代理請求參數
var proxyParams = {
requesturl: opts.targetUrl,
typedata: 'JSON',
method: opts.method.toUpperCase()
};
// 將業務參數攤平加入代理參數
$.each(opts.params, function(key, val) {
proxyParams[key] = val;
});
// 發送至本地代理 Servlet
return $.ajax({
url: '/cross/proxy', // 代理 Servlet 路徑
type: 'POST',
dataType: 'json',
timeout: opts.timeout,
data: proxyParams,
headers: opts.headers,
// 重要:同步請求會阻塞 UI,生產環境請改用 Promise/async-await
async: true
}).then(function(proxyResponse) {
// 代理成功回傳目標 API 原始回應
return proxyResponse;
}).fail(function(xhr, status, error) {
// 代理層面的錯誤(網路、超時、500等)
var msg = '代理請求失敗:' + status;
if (xhr.responseJSON && xhr.responseJSON.message) msg += ' - ' + xhr.responseJSON.message;
throw new Error(msg);
});
}
// 使用範例
// GET 請求
crossDomainRequest({
targetUrl: 'https://api.example.com/users',
params: { page: 1, limit: 20 }
}).done(function(data) {
console.log('用戶列表:', data);
}).fail(function(err) {
console.error(err);
});
// POST 請求
crossDomainRequest({
targetUrl: 'https://api.example.com/orders',
method: 'POST',
params: { productId: 123, quantity: 2 },
headers: { 'Authorization': 'Bearer token123' }
}).done(function(data) {
console.log('訂單建立:', data);
});
package com.example.proxy;
import jakarta.servlet.*;
import jakarta.servlet.http.*;
import jakarta.servlet.annotation.*;
import org.apache.http.client.methods.*;
import org.apache.http.impl.client.*;
import org.apache.http.util.EntityUtils;
import org.apache.http.entity.StringEntity;
import java.io.*;
import java.util.*;
@WebServlet("/cross/proxy")
public class CrossDomainProxyServlet extends HttpServlet {
private static final CloseableHttpClient httpClient = HttpClients.custom()
.setMaxConnTotal(100)
.setMaxConnPerRoute(20)
.evictIdleConnections(30, TimeUnit.SECONDS)
.build();
@Override
protected void doPost(HttpServletRequest req, HttpServletResponse resp)
throws ServletException, IOException {
// 1. 解析前端傳入參數
String targetUrl = req.getParameter("requesturl");
String method = req.getParameter("method") != null ? req.getParameter("method").toUpperCase() : "GET";
if (targetUrl == null || targetUrl.isEmpty()) {
sendError(resp, 400, "缺少 requesturl 參數");
return;
}
// 安全性:驗證目標 URL 白名單(防止 SSRF 攻擊)
if (!isAllowedDomain(targetUrl)) {
sendError(resp, 403, "目標網域不在白名單中");
return;
}
// 2. 收集業務參數(排除代理控制參數)
Map businessParams = new HashMap<>();
Enumeration paramNames = req.getParameterNames();
while (paramNames.hasMoreElements()) {
String key = paramNames.nextElement();
if (!isProxyControlParam(key)) {
businessParams.put(key, req.getParameter(key));
}
}
// 3. 建立目標請求
HttpRequestBase targetReq;
if ("POST".equals(method) || "PUT".equals(method) || "PATCH".equals(method)) {
HttpEntityEnclosingRequestBase entityReq = "POST".equals(method)
? new HttpPost(targetUrl) : new HttpPut(targetUrl);
// 設定請求體(表單或 JSON)
String contentType = req.getHeader("Content-Type");
if (contentType != null && contentType.contains("application/json")) {
// JSON 直接透傳
String jsonBody = new BufferedReader(req.getReader()).lines()
.collect(Collectors.joining("\n"));
entityReq.setEntity(new StringEntity(jsonBody, "UTF-8"));
entityReq.setHeader("Content-Type", "application/json");
} else {
// 表單參數
List formParams = new ArrayList<>();
businessParams.forEach((k, v) -> formParams.add(new BasicNameValuePair(k, v)));
entityReq.setEntity(new UrlEncodedFormEntity(formParams, "UTF-8"));
}
targetReq = entityReq;
} else {
// GET/DELETE:參數附加到 URL
String queryString = businessParams.entrySet().stream()
.map(e -> e.getKey() + "=" + URLEncoder.encode(e.getValue(), "UTF-8"))
.collect(Collectors.joining("&"));
String urlWithQuery = targetUrl + (targetUrl.contains("?") ? "&" : "?") + queryString;
targetReq = new HttpGet(urlWithQuery);
}
// 透傳重要標頭(可配置白名單)
forwardHeaders(req, targetReq);
// 4. 執行請求並回傳
try (CloseableHttpResponse targetResp = httpClient.execute(targetReq)) {
int statusCode = targetResp.getStatusLine().getStatusCode();
String responseBody = EntityUtils.toString(targetResp.getEntity(), "UTF-8");
resp.setStatus(statusCode);
resp.setContentType(targetResp.getFirstHeader("Content-Type") != null
? targetResp.getFirstHeader("Content-Type").getValue()
: "application/json; charset=UTF-8");
resp.getWriter().write(responseBody);
} catch (Exception e) {
sendError(resp, 502, "上游服務錯誤:" + e.getMessage());
}
}
@Override
protected void doGet(HttpServletRequest req, HttpServletResponse resp)
throws ServletException, IOException {
doPost(req, resp); // 統一處理
}
// ===== 輔助方法 =====
private boolean isProxyControlParam(String key) {
return "requesturl".equalsIgnoreCase(key)
|| "typedata".equalsIgnoreCase(key)
|| "method".equalsIgnoreCase(key)
|| "returntype".equalsIgnoreCase(key);
}
private boolean isAllowedDomain(String url) {
try {
var uri = new java.net.URI(url);
String host = uri.getHost();
// 實際專案應從設定檔讀取白名單
return "api.example.com".equals(host)
|| "api.trusted-partner.com".equals(host);
} catch (Exception e) {
return false;
}
}
private void forwardHeaders(HttpServletRequest src, HttpRequestBase dest) {
String[] allowedHeaders = {"Authorization", "Accept", "Content-Type", "User-Agent"};
for (String h : allowedHeaders) {
String val = src.getHeader(h);
if (val != null) dest.setHeader(h, val);
}
}
private void sendError(HttpServletResponse resp, int code, String msg) throws IOException {
resp.setStatus(code);
resp.setContentType("application/json; charset=UTF-8");
resp.getWriter().write("{\"success\":false,\"message\":\"" + msg.replace("\"", "\\\"") + "\"}");
}
}
代理 Servlet 本質上是一個「伺服器端請求偽造 (SSRF)」風險點。必須實作嚴格白名單驗證:
AsyncContext 釋放執行緒jQuery + Servlet 跨域代理是經典解決方案,適合無法修改目標 API、且後端為 Java 技術棧的專案。核心在於:前端統一發送至同源代理端點,代理解析參數、驗證白名單、轉發請求、透傳回應。務必實作 SSRF 防護,否則會成為嚴重安全漏洞。現代架構建議遷移至 API Gateway 或 BFF 模式,將跨域處理從業務邏輯中剝離。