• 為什么有的接口直接寫 DTO 就能接收參數(shù)？
• @PathVariable、@RequestParam、@RequestBody 到底什么時(shí)候用？
• GET 請求能不能傳 JSON？路徑參數(shù)和查詢參數(shù)怎么區(qū)分？
• 省市區(qū)聯(lián)動(dòng)接口該如何設(shè)計(jì)傳參和返回值？

本文結(jié)合真實(shí)業(yè)務(wù)代碼，用最通俗的語言，把 SpringBoot 接口傳參的所有核心知識(shí)點(diǎn)講透，新手看完直接上手！

一、SpringBoot 三大傳參方式（核心必背）

SpringBoot 接口傳參分為 3 種標(biāo)準(zhǔn)場景，對應(yīng)不同的請求類型和業(yè)務(wù)需求，嚴(yán)格遵循 HTTP 協(xié)議規(guī)范。

URL 查詢參數(shù)（? 后面的參數(shù)）→ 最常用

適用場景：GET 請求、查詢列表、多條件篩選、省市區(qū)聯(lián)動(dòng)等獲取數(shù)據(jù)的場景接收寫法：直接寫 DTO / 實(shí)體類，無需任何注解，Spring 自動(dòng)封裝參數(shù)前端傳參：/api/linkage?parentId=0&level=1

// 你的省市區(qū)聯(lián)動(dòng)接口（標(biāo)準(zhǔn)查詢參數(shù)寫法）
@GetMapping("/linkage")
public ApiResponse<List<CountryAreaOptionDTO>> linkage(
    @Valid CountryAreaLinkageQueryDTO request // 自動(dòng)封裝所有查詢參數(shù)
) {
    return ApiResponse.success(countryAreaDOService.queryLinkage(request));
}

路徑參數(shù)（/xxx/{id}）→ 操作單個(gè)資源

適用場景：根據(jù)唯一 ID查詢 / 刪除 / 修改單個(gè)資源（RESTful 規(guī)范）接收寫法：必須加 @PathVariable 注解前端傳參：/api/area/1001

// 查詢單個(gè)地區(qū)詳情（路徑參數(shù)寫法）
@GetMapping("/area/{areaId}")
public ApiResponse<CountryAreaDO> getAreaById(
    @PathVariable Long areaId // 接收路徑中的ID
) {
    return ApiResponse.success(countryAreaDOService.getById(areaId));
}

JSON 請求體參數(shù) → 增 / 改數(shù)據(jù)

適用場景：POST/PUT 請求、提交大量數(shù)據(jù)、復(fù)雜對象參數(shù)接收寫法：必須加 @RequestBody 注解前端傳參：JSON 格式放在請求體中

// 新增地區(qū)（JSON參數(shù)寫法）
@PostMapping("/area/save")
public ApiResponse<Boolean> saveArea(
    @RequestBody CountryAreaDO areaDO // 接收J(rèn)SON參數(shù)
) {
    return ApiResponse.success(countryAreaDOService.save(areaDO));
}

三大傳參方式對比表

表格

二、關(guān)鍵區(qū)分：DTO 自動(dòng)封裝 vs @RequestParam

新手最容易混淆：加不加 @RequestParam 的區(qū)別，一句話搞定：

• 不加注解：自動(dòng)把前端所有參數(shù)封裝成 DTO 對象
• 加 @RequestParam：只提取前端的單個(gè)參數(shù)

不加注解 → 自動(dòng)封裝 DTO

前端傳多個(gè)參數(shù)，Spring 自動(dòng)匹配字段，封裝成對象：

// 前端：?parentId=0&level=1 → 自動(dòng)封裝進(jìn)DTO
@GetMapping("/linkage")
public ApiResponse linkage(CountryAreaLinkageQueryDTO request) {}

加@RequestParam→ 提取單個(gè)參數(shù)

只需要前端的某一個(gè)參數(shù)，單獨(dú)接收：

// 只接收 provinceId 這一個(gè)參數(shù)
@GetMapping("/cities")
public ApiResponse cities(@RequestParam Long provinceId) {}

禁忌

千萬不要給 DTO 加 @RequestParam，會(huì)直接報(bào)錯(cuò)！

三、核心鐵律：GET 請求絕對不用 JSON

這是 HTTP 協(xié)議的固定規(guī)則，企業(yè)開發(fā)強(qiáng)制遵守：

1. GET 請求沒有請求體，強(qiáng)行傳 JSON 會(huì)被服務(wù)器丟棄
2. GET 參數(shù)只能放在 URL 中，適合查詢、非敏感數(shù)據(jù)
3. 只有 POST/PUT 才用 JSON 參數(shù)

四、實(shí)戰(zhàn)案例：省市區(qū)多級(jí)聯(lián)動(dòng)接口設(shè)計(jì)

結(jié)合你的業(yè)務(wù)需求，不修改數(shù)據(jù)庫、不新增字段，純后端實(shí)現(xiàn)省市區(qū)聯(lián)動(dòng)，完整方案如下：

前端傳參規(guī)則

• 查省份：/provinces（parentId=0）
• 查城市：/cities?provinceId=xxx
• 查區(qū)縣：/districts?cityId=xxx
• 通用接口：/linkage?parentId=xxx

后端核心代碼（層級(jí)判斷邏輯）

不靠數(shù)據(jù)庫 level 字段，純通過父 ID 判斷省 / 市 / 區(qū)：

// 核心聯(lián)動(dòng)查詢方法
public List<CountryAreaOptionDTO> queryLinkage(Long parentId) {
    // 1. 查詢當(dāng)前層級(jí)數(shù)據(jù)
    List<CountryAreaDO> areas = parentId == null
            ? list(Wrappers.<CountryAreaDO>lambdaQuery().isNull(CountryAreaDO::getPid))
            : list(Wrappers.<CountryAreaDO>lambdaQuery().eq(CountryAreaDO::getPid, parentId));

    // 2. 獲取所有父ID集合（判斷是否有子節(jié)點(diǎn)）
    Set<Long> parentIds = list(Wrappers.<CountryAreaDO>lambdaQuery().isNotNull(CountryAreaDO::getPid))
            .stream().map(CountryAreaDO::getPid).collect(Collectors.toSet());

    // 3. 自動(dòng)判斷層級(jí)：省/市/區(qū)
    return areas.stream().map(area -> toOption(area, level, parentIds)).toList();
}

// 層級(jí)判斷規(guī)則
parentId == null ? 省份 : parentIds.contains(area.getId()) ? 市 : 區(qū)

3. 前端接收 DTO（標(biāo)準(zhǔn)返回值）

@Data
public class CountryAreaOptionDTO {
    private Long id;        // 下一級(jí)查詢的parentId
    private String name;   // 前端展示名稱
    private String level;  // 層級(jí)編碼
    private String levelDesc; // 省/市/區(qū)
    private boolean hasChildren; // 是否有子節(jié)點(diǎn)
}

五、新手常見問題：為什么項(xiàng)目不能本地啟動(dòng)？

很多新手發(fā)現(xiàn)：有的項(xiàng)目能啟動(dòng)，有的不能，核心原因只有一個(gè)：項(xiàng)目運(yùn)行環(huán)境 / 配置不滿足，和項(xiàng)目本身無關(guān)！

最常見 4 個(gè)啟動(dòng)失敗原因

1. 端口被占用：8080 端口被其他軟件占用
2. 數(shù)據(jù)庫連接失敗：MySQL 未啟動(dòng)、賬號(hào)密碼錯(cuò)誤
3. Maven 依賴未下載完：代碼全紅，編譯失敗
4. 配置文件語法錯(cuò)誤：yml 縮進(jìn)錯(cuò)誤

10 秒排查方法

看控制臺(tái)第一行紅字：

• 含 port → 換端口
• 含 MySQL → 檢查數(shù)據(jù)庫
• 含 dependency → 重新加載 Maven

六、新手必背口訣（記住永不踩坑）

1. 查數(shù)據(jù)用 GET，參數(shù)放？后面，直接寫 DTO
2. 單資源查改刪，用路徑參數(shù)，加 @PathVariable
3. 增改數(shù)據(jù)用 POST，傳 JSON，加 @RequestBody
4. 不加注解封 DTO，加注解取單個(gè)參數(shù)
5. GET 不用 JSON，路徑參數(shù)只傳 ID

總結(jié)

本文覆蓋了 SpringBoot 接口傳參的所有核心知識(shí)點(diǎn)，結(jié)合省市區(qū)聯(lián)動(dòng)真實(shí)業(yè)務(wù)，從基礎(chǔ)用法到實(shí)戰(zhàn)設(shè)計(jì)，徹底解決新手傳參困惑。

SpringBoot 傳參沒有復(fù)雜邏輯，嚴(yán)格遵循規(guī)范，結(jié)合業(yè)務(wù)場景選擇對應(yīng)的方式，就能寫出規(guī)范、可維護(hù)的接口代碼！

以上就是新手必懂的SpringBoot接口傳參全攻略:查詢參數(shù)/路徑參數(shù)/JSON 參數(shù)的詳細(xì)內(nèi)容，更多關(guān)于SpringBoot接口傳參的資料請關(guān)注腳本之家其它相關(guān)文章！

最新評論