為 Android App 提供 RESTful JSON 接口：設計規範與實踐指南

核心需求拆解

現有成熟 Java Web 專案需為 Android App 提供數據接口。關鍵問題在於：接口輸入輸出格式如何定義？Java 對象如何序列化為 JSON？前端如何反序列化？如何約定請求參數結構？

接口設計最佳實踐

• 統一採用 JSON：請求體與響應體均使用 JSON，Content-Type 設置為 application/json; charset=UTF-8。
• 定義清晰的契約：提供 Swagger/OpenAPI 文檔，明確每個端點的 URL、HTTP 方法、請求參數、響應結構、錯誤碼。
• Java 對象自動序列化：使用 Jackson、Gson 或 Spring MVC 內置 @ResponseBody，直接返回 POJO，框架自動轉為 JSON，無需手動放入 Map。
• 請求參數綁定：前端傳 JSON，後端用 @RequestBody 直接映射到 Java 對象，類型安全且結構清晰。
• 統一響應包裝：{"code":200,"msg":"success","data":{...}} 便於前端統一錯誤處理。

具體實現要點

@PostMapping("/api/user/login")
public Result<UserVO> login(@RequestBody LoginDTO dto) {
    // 業務邏輯
    return Result.success(userService.login(dto));
}

前端 Android 端使用 Retrofit + Gson/Jackson 定義同樣的數據類，即可自動完成雙向轉換。無需雙方協商「類的方式」，JSON 文本本身即是跨語言的通用契約。

安全與性能建議

• 全站 HTTPS，敏感接口加簽名/Token 驗證。
• 分頁查詢必須限制最大頁面大小，防止 OOM。
• 啟用 GZIP 壓縮，減少流量。
• 接口版本化，如 /v1/ 前綴，平滑演進。