如何做醫(yī)療網(wǎng)站的專題頁,網(wǎng)站建設(shè)綜合訓(xùn)練報告,哈爾濱網(wǎng)站建設(shè)王道下拉強,物聯(lián)網(wǎng)水表RESTful API 的請求和響應(yīng)格式詳解 在 RESTful API 中#xff0c;請求和響應(yīng)的格式設(shè)計直接影響 API 的易用性、一致性和可維護性。優(yōu)秀的格式規(guī)范能讓前后端開發(fā)者快速理解接口行為#xff0c;減少溝通成本。 1. 總體原則 內(nèi)容類型統(tǒng)一#xff1a;幾乎全部使用 JSON請求和響應(yīng)的格式設(shè)計直接影響 API 的易用性、一致性和可維護性。優(yōu)秀的格式規(guī)范能讓前后端開發(fā)者快速理解接口行為減少溝通成本。1. 總體原則內(nèi)容類型統(tǒng)一幾乎全部使用JSONapplication/json作為請求和響應(yīng)的數(shù)據(jù)格式。結(jié)構(gòu)一致成功響應(yīng)和錯誤響應(yīng)都采用統(tǒng)一的包裹結(jié)構(gòu)便于客戶端統(tǒng)一處理。清晰、可讀字段命名規(guī)范時間格式標(biāo)準(zhǔn)返回必要元信息。避免裸數(shù)據(jù)不要直接返回數(shù)組或單個對象而是用包裹對象提供上下文。2. 請求格式Request2.1 常見 Content-TypeHTTP 方法典型 Content-Type說明POST / PUT / PATCHapplication/json最常用發(fā)送 JSON 數(shù)據(jù)文件上傳multipart/form-data上傳頭像、附件等表單提交application/x-www-form-urlencoded傳統(tǒng)表單較少用2.2 請求體Body示例創(chuàng)建用戶POST /users{name:張三,email:zhangexample.com,password:secret123,age:28,roles:[user,admin]}部分更新用戶PATCH /users/123{name:張三豐,age:30}只包含需要修改的字段查詢參數(shù)Query Parameters用于 GET 請求過濾GET /articles?statuspublishedtagrestsort-created_atpage2limit202.3 請求頭Headers常用字段Header示例值說明Content-Typeapplication/json請求體格式Acceptapplication/json期望響應(yīng)格式AuthorizationBearer eyJhbGciOiJIUzI1NiIs…JWT 或其他認(rèn)證令牌X-API-Keyyour-api-keyAPI Key 認(rèn)證3. 響應(yīng)格式Response3.1 成功響應(yīng)統(tǒng)一結(jié)構(gòu)推薦方案一通用包裹最常用{data:{// 主要數(shù)據(jù)id:123,name:張三,email:zhangexample.com,created_at:2025-12-25T10:00:00Z},meta:{// 元信息可選timestamp:2025-12-25T10:00:01Z,request_id:abc123-def456}}方案二集合響應(yīng)列表 分頁{data:[{id:1,title:REST 教程},{id:2,title:API 設(shè)計}],meta:{pagination:{total:156,page:2,limit:20,total_pages:8},timestamp:2025-12-25T10:00:01Z}}方案三無數(shù)據(jù)內(nèi)容如 DELETE 成功返回204 No Content無響應(yīng)體最推薦或返回 200 簡單結(jié)構(gòu){data:null,meta:{message:用戶刪除成功}}3.2 錯誤響應(yīng)統(tǒng)一結(jié)構(gòu)非常重要推薦錯誤格式Problem Details - RFC 7807 標(biāo)準(zhǔn){error:{code:VALIDATION_ERROR,// 業(yè)務(wù)錯誤碼字符串message:請求參數(shù)驗證失敗,// 給開發(fā)者的友好提示details:[// 具體字段錯誤可選{field:email,issue:already_exists,message:該郵箱已被注冊},{field:age,issue:invalid_range,message:年齡必須在 18-100 之間}]}}響應(yīng)頭Content-Type: application/jsonHTTP 狀態(tài)碼400 Bad Request、422 Unprocessable Entity 等常見錯誤狀態(tài)碼與 code 對應(yīng)HTTP 狀態(tài)碼推薦 error.code場景400BAD_REQUEST參數(shù)格式錯誤401UNAUTHORIZED未登錄403FORBIDDEN無權(quán)限404NOT_FOUND資源不存在409CONFLICT資源沖突如用戶名重復(fù)422VALIDATION_ERROR業(yè)務(wù)校驗失敗最常用429TOO_MANY_REQUESTS限流500INTERNAL_SERVER_ERROR服務(wù)器異常3.3 字段命名與數(shù)據(jù)格式規(guī)范項目推薦規(guī)范示例字段命名snake_case下劃線或 camelCaseuser_id或userId統(tǒng)一即可時間格式ISO 8601UTC“2025-12-25T10:00:00Z”布爾值true / false“is_active”: true空值null避免空字符串“description”: null枚舉字符串常量“status”: “published”4. 完整示例對比請求POST /api/v1/users HTTP/1.1 Content-Type: application/json Authorization: Bearer xyz123... { name: 李四, email: liexample.com, password: 123456 }成功響應(yīng)201 CreatedHTTP/1.1 201 Created Content-Type: application/json Location: /api/v1/users/456 { data: { id: 456, name: 李四, email: liexample.com, created_at: 2025-12-25T10:00:00Z }, meta: { timestamp: 2025-12-25T10:00:01Z } }錯誤響應(yīng)422HTTP/1.1 422 Unprocessable Entity Content-Type: application/json { error: { code: VALIDATION_ERROR, message: 參數(shù)驗證失敗, details: [ { field: email, issue: invalid_format, message: 郵箱格式不正確 } ] } }5. 總結(jié)口訣請求簡潔 JSON響應(yīng)統(tǒng)一包裹錯誤結(jié)構(gòu)化提示狀態(tài)碼要準(zhǔn)確遵循這些格式規(guī)范你的 RESTful API 將更加專業(yè)、一致便于前端統(tǒng)一封裝錯誤處理和數(shù)據(jù)解析。如果你想看特定框架如 Spring Boot、Express、FastAPI的響應(yīng)封裝代碼實現(xiàn)或者 OpenAPI/Swagger 如何描述這些格式歡迎繼續(xù)問