🐛 fix(handlers): 统一错误响应为安全 JSON 并补参数校验

- 新增 respondError：JSON 安全编码，客户端错误返回 400，服务端错误返回 500
- 收编 book/content/media/category 中 13 处 fmt.Fprintf 内联 JSON，修复错误信息含引号/换行时产出非法 JSON 的问题
- search/detail/catalog/multi-detail/content/multi-content/item-summary/audio/video 补必需参数校验，缺参返回 400
- search 的 offset/tab_type 非数字时返回 400，不再静默置 0
- 补齐 multi-detail/multi-content 的请求统计计数
- 新增 error_response_test.go：3 个测试锁定错误响应行为
- openapi.yaml 新增 ServerError 响应组件，15 个业务接口补 400/500 响应定义

BREAKING CHANGE: 业务接口错误不再返回 HTTP 200，缺参返回 400，上游失败返回 500

internal/handlers/book.go

@@ -4,7 +4,6 @@ import (
 	"fanqie/internal/fqapi"
 	"fmt"
 	"net/http"
-	"strconv"
 )
 
 // HandleSearch 搜索处理
@@ -16,22 +15,29 @@ func HandleSearch(w http.ResponseWriter, r *http.Request) {
 	if query == "" {
 		query = r.URL.Query().Get("key")
 	}
-
+	if query == "" {
-	offsetStr := r.URL.Query().Get("offset")
+		respondError(w, "缺少 query 参数", true)
-	offset := 0
+		return
-	if offsetStr != "" {
-		offset, _ = strconv.Atoi(offsetStr)
 	}
 
-	tabTypeStr := r.URL.Query().Get("tab_type")
+	offset, err := parseIntParam(r.URL.Query().Get("offset"), "offset")
-	tabType := 3
+	if err != nil {
-	if tabTypeStr != "" {
+		respondError(w, err.Error(), true)
-		tabType, _ = strconv.Atoi(tabTypeStr)
+		return
+	}
+
+	tabType, err := parseIntParam(r.URL.Query().Get("tab_type"), "tab_type")
+	if err != nil {
+		respondError(w, err.Error(), true)
+		return
+	}
+	if tabType == 0 {
+		tabType = 3
 	}
 
 	result, err := fqapi.HandleBookSearch(query, offset, tabType)
 	if err != nil {
-		fmt.Fprintf(w, `{"code": -1, "msg": "搜索失败: %s"}`, err.Error())
+		respondError(w, "搜索失败: "+err.Error(), false)
 		return
 	}
 
@@ -43,11 +49,15 @@ func HandleDetail(w http.ResponseWriter, r *http.Request) {
 	incrementStat("total", "detail")
 	w.Header().Set("Content-Type", "application/json; charset=utf-8")
 
-	bookID := r.URL.Query().Get("book_id")
+	params, err := validateParams(r, "book_id")
-
-	result, err := fqapi.HandleGetDetail(bookID)
 	if err != nil {
-		fmt.Fprintf(w, `{"code": -1, "msg": "获取详情失败: %s"}`, err.Error())
+		respondError(w, err.Error(), true)
+		return
+	}
+
+	result, err := fqapi.HandleGetDetail(params["book_id"])
+	if err != nil {
+		respondError(w, "获取详情失败: "+err.Error(), false)
 		return
 	}
 
@@ -59,11 +69,15 @@ func HandleCatalog(w http.ResponseWriter, r *http.Request) {
 	incrementStat("total", "catalog")
 	w.Header().Set("Content-Type", "application/json; charset=utf-8")
 
-	bookID := r.URL.Query().Get("book_id")
+	params, err := validateParams(r, "book_id")
-
-	result, err := fqapi.HandleGetCatalog(bookID)
 	if err != nil {
-		fmt.Fprintf(w, `{"code": -1, "msg": "获取目录失败: %s"}`, err.Error())
+		respondError(w, err.Error(), true)
+		return
+	}
+
+	result, err := fqapi.HandleGetCatalog(params["book_id"])
+	if err != nil {
+		respondError(w, "获取目录失败: "+err.Error(), false)
 		return
 	}
 
@@ -72,13 +86,18 @@ func HandleCatalog(w http.ResponseWriter, r *http.Request) {
 
 // HandleMultiDetail 批量详情处理
 func HandleMultiDetail(w http.ResponseWriter, r *http.Request) {
+	incrementStat("total", "detail")
 	w.Header().Set("Content-Type", "application/json; charset=utf-8")
 
-	bookID := r.URL.Query().Get("book_id")
+	params, err := validateParams(r, "book_id")
-
-	result, err := fqapi.HandleGetMultiDetail(bookID)
 	if err != nil {
-		fmt.Fprintf(w, `{"code": -1, "msg": "批量获取详情失败: %s"}`, err.Error())
+		respondError(w, err.Error(), true)
+		return
+	}
+
+	result, err := fqapi.HandleGetMultiDetail(params["book_id"])
+	if err != nil {
+		respondError(w, "批量获取详情失败: "+err.Error(), false)
 		return
 	}
 

internal/handlers/category.go

@@ -15,7 +15,7 @@ func HandleCategoryFront(w http.ResponseWriter, r *http.Request) {
 
 	result, err := fqapi.HandleCategoryFront(tab)
 	if err != nil {
-		fmt.Fprintf(w, `{"code": -1, "msg": "获取分类列表失败: %s"}`, err.Error())
+		respondError(w, "获取分类列表失败: "+err.Error(), false)
 		return
 	}
 
@@ -35,7 +35,7 @@ func HandleCategoryLanding(w http.ResponseWriter, r *http.Request) {
 
 	result, err := fqapi.HandleCategoryLanding(categoryID, offset, wordNumber, bookStatus, sortBy)
 	if err != nil {
-		fmt.Fprintf(w, `{"code": -1, "msg": "获取分类详情失败: %s"}`, err.Error())
+		respondError(w, "获取分类详情失败: "+err.Error(), false)
 		return
 	}
 

internal/handlers/common.go

@@ -96,6 +96,15 @@ func StopStatisticsSaver() {
 	}
 }
 
+// respondError 统一错误响应（JSON 安全编码；isClientErr 为 true 时返回 400，否则 500）
+func respondError(w http.ResponseWriter, msg string, isClientErr bool) {
+	status := http.StatusInternalServerError
+	if isClientErr {
+		status = http.StatusBadRequest
+	}
+	respondJSON(w, status, map[string]interface{}{"code": -1, "msg": msg})
+}
+
 // RequireAccessKey 验证访问密钥中间件
 func RequireAccessKey(handler http.HandlerFunc) http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {

internal/handlers/content.go

@@ -12,8 +12,12 @@ func HandleContent(w http.ResponseWriter, r *http.Request) {
 	incrementStat("total", "content")
 	w.Header().Set("Content-Type", "application/json; charset=utf-8")
 
-	// 从查询参数获取item_id
+	params, err := validateParams(r, "item_id")
-	itemID := r.URL.Query().Get("item_id")
+	if err != nil {
+		respondError(w, err.Error(), true)
+		return
+	}
+	itemID := params["item_id"]
 
 	// 获取URL参数（支持动态覆盖配置）
 	textMode := r.URL.Query().Get("text_mode")     // 1=纯文本模式
@@ -22,7 +26,7 @@ func HandleContent(w http.ResponseWriter, r *http.Request) {
 
 	result, err := fqapi.HandleGetContent(itemID, textMode, imageMode)
 	if err != nil {
-		fmt.Fprintf(w, `{"code": -1, "msg": "获取内容失败: %s"}`, err.Error())
+		respondError(w, "获取内容失败: "+err.Error(), false)
 		return
 	}
 
@@ -51,17 +55,22 @@ func HandleContent(w http.ResponseWriter, r *http.Request) {
 
 // HandleMultiContent 批量内容处理
 func HandleMultiContent(w http.ResponseWriter, r *http.Request) {
+	incrementStat("total", "content")
 	w.Header().Set("Content-Type", "application/json; charset=utf-8")
 
-	bookID := r.URL.Query().Get("book_id")
+	params, err := validateParams(r, "book_id", "item_ids")
-	itemIDs := r.URL.Query().Get("item_ids")
+	if err != nil {
+		respondError(w, err.Error(), true)
+		return
+	}
+
 	textMode := r.URL.Query().Get("text_mode")
 	imageMode := r.URL.Query().Get("image_mode")
 	ignoreFailed := r.URL.Query().Get("ignore_failed")
 
-	result, err := fqapi.HandleMultiContent(itemIDs, bookID, textMode, imageMode, ignoreFailed)
+	result, err := fqapi.HandleMultiContent(params["item_ids"], params["book_id"], textMode, imageMode, ignoreFailed)
 	if err != nil {
-		fmt.Fprintf(w, `{"code": -1, "msg": "批量获取内容失败: %s"}`, err.Error())
+		respondError(w, "批量获取内容失败: "+err.Error(), false)
 		return
 	}
 
@@ -72,12 +81,15 @@ func HandleMultiContent(w http.ResponseWriter, r *http.Request) {
 func HandleItemSummary(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("Content-Type", "application/json; charset=utf-8")
 
-	bookID := r.URL.Query().Get("book_id")
+	params, err := validateParams(r, "book_id", "item_ids")
-	itemIDs := r.URL.Query().Get("item_ids")
-
-	result, err := fqapi.HandleItemSummary(itemIDs, bookID)
 	if err != nil {
-		fmt.Fprintf(w, `{"code": -1, "msg": "获取章节摘要失败: %s"}`, err.Error())
+		respondError(w, err.Error(), true)
+		return
+	}
+
+	result, err := fqapi.HandleItemSummary(params["item_ids"], params["book_id"])
+	if err != nil {
+		respondError(w, "获取章节摘要失败: "+err.Error(), false)
 		return
 	}
 

internal/handlers/error_response_test.go

@@ -0,0 +1,42 @@
+package handlers
+
+import (
+	"encoding/json"
+	"net/http/httptest"
+	"testing"
+)
+
+// TestRespondErrorProducesValidJSON 错误信息含引号/换行时输出仍须是合法 JSON
+func TestRespondErrorProducesValidJSON(t *testing.T) {
+	w := httptest.NewRecorder()
+	respondError(w, "上游返回了 \"引号\" 和\n换行", false)
+
+	var body map[string]interface{}
+	if err := json.Unmarshal(w.Body.Bytes(), &body); err != nil {
+		t.Fatalf("非法 JSON: %v, body: %s", err, w.Body.String())
+	}
+	if body["code"].(float64) != -1 {
+		t.Errorf("code 应为 -1, got %v", body["code"])
+	}
+	if w.Code != 500 {
+		t.Errorf("服务端错误应返回 500, got %d", w.Code)
+	}
+}
+
+// TestRespondErrorClientErr 客户端错误应返回 400
+func TestRespondErrorClientErr(t *testing.T) {
+	w := httptest.NewRecorder()
+	respondError(w, "缺少 book_id 参数", true)
+	if w.Code != 400 {
+		t.Errorf("客户端错误应返回 400, got %d", w.Code)
+	}
+}
+
+// TestHandleDetailMissingParam 缺少必需参数返回 400 而非透传到上游
+func TestHandleDetailMissingParam(t *testing.T) {
+	w := httptest.NewRecorder()
+	HandleDetail(w, httptest.NewRequest("GET", "/detail", nil))
+	if w.Code != 400 {
+		t.Errorf("缺参应返回 400, got %d, body: %s", w.Code, w.Body.String())
+	}
+}

internal/handlers/media.go

@@ -13,13 +13,18 @@ func HandleAudio(w http.ResponseWriter, r *http.Request) {
 	incrementStat("total", "audio")
 	w.Header().Set("Content-Type", "application/json; charset=utf-8")
 
-	itemIDs := r.URL.Query().Get("item_ids")
+	params, err := validateParams(r, "item_ids")
+	if err != nil {
+		respondError(w, err.Error(), true)
+		return
+	}
+
 	toneID := r.URL.Query().Get("tone_id")
 	output := r.URL.Query().Get("output")
 
-	result, err := fqapi.HandleAudio(itemIDs, toneID, output)
+	result, err := fqapi.HandleAudio(params["item_ids"], toneID, output)
 	if err != nil {
-		fmt.Fprintf(w, `{"code": -1, "msg": "获取音频失败: %s"}`, err.Error())
+		respondError(w, "获取音频失败: "+err.Error(), false)
 		return
 	}
 
@@ -62,11 +67,15 @@ func HandleVideo(w http.ResponseWriter, r *http.Request) {
 	incrementStat("total", "video")
 	w.Header().Set("Content-Type", "application/json; charset=utf-8")
 
-	itemIDs := r.URL.Query().Get("item_ids")
+	params, err := validateParams(r, "item_ids")
-
-	result, err := fqapi.HandleVideo(itemIDs)
 	if err != nil {
-		fmt.Fprintf(w, `{"code": -1, "msg": "获取视频失败: %s"}`, err.Error())
+		respondError(w, err.Error(), true)
+		return
+	}
+
+	result, err := fqapi.HandleVideo(params["item_ids"])
+	if err != nil {
+		respondError(w, "获取视频失败: "+err.Error(), false)
 		return
 	}
 
@@ -76,14 +85,13 @@ func HandleVideo(w http.ResponseWriter, r *http.Request) {
 // HandleManga 漫画处理
 func HandleManga(w http.ResponseWriter, r *http.Request) {
 	incrementStat("total", "manga")
+
 	itemID := r.URL.Query().Get("item_ids")
 	if itemID == "" {
 		itemID = r.URL.Query().Get("item_id")
 	}
-
 	if itemID == "" {
-		w.Header().Set("Content-Type", "application/json; charset=utf-8")
+		respondError(w, "缺少 item_ids 参数", true)
-		fmt.Fprint(w, `{"code": -1, "msg": "缺少item_ids参数"}`)
 		return
 	}
 
@@ -96,8 +104,7 @@ func HandleManga(w http.ResponseWriter, r *http.Request) {
 
 	result, err := fqapi.HandleGetManga(itemID, showHTML, outputMode)
 	if err != nil {
-		w.Header().Set("Content-Type", "application/json; charset=utf-8")
+		respondError(w, "获取漫画失败: "+err.Error(), false)
-		fmt.Fprintf(w, `{"code": -1, "msg": "获取漫画失败: %s"}`, err.Error())
 		return
 	}
 
@@ -113,16 +120,16 @@ func HandleManga(w http.ResponseWriter, r *http.Request) {
 		fmt.Fprint(w, `<p>未找到漫画内容</p>`)
 	} else {
 		// 返回JSON格式
-		w.Header().Set("Content-Type", "application/json; charset=utf-8")
 		jsonData, err := json.Marshal(map[string]interface{}{
 			"code": 0,
 			"msg":  "success",
 			"data": result,
 		})
 		if err != nil {
-			fmt.Fprintf(w, `{"code": -1, "msg": "JSON编码失败: %s"}`, err.Error())
+			respondError(w, "JSON编码失败: "+err.Error(), false)
 			return
 		}
+		w.Header().Set("Content-Type", "application/json; charset=utf-8")
 		fmt.Fprint(w, string(jsonData))
 	}
 }

openapi.yaml

@@ -169,6 +169,10 @@ paths:
                 $ref: "#/components/schemas/UpstreamResponse"
               example: { code: 0, msg: success, data: { search_book_data_list: [], has_more: 1 } }
 
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "500":
+          $ref: "#/components/responses/ServerError"
   /detail:
     get:
       tags: [书籍]
@@ -183,6 +187,10 @@ paths:
             application/json:
               schema: { $ref: "#/components/schemas/UpstreamResponse" }
 
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "500":
+          $ref: "#/components/responses/ServerError"
   /info:
     get:
       tags: [书籍]
@@ -197,6 +205,10 @@ paths:
             application/json:
               schema: { $ref: "#/components/schemas/UpstreamResponse" }
 
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "500":
+          $ref: "#/components/responses/ServerError"
   /catalog:
     get:
       tags: [书籍]
@@ -211,6 +223,10 @@ paths:
             application/json:
               schema: { $ref: "#/components/schemas/UpstreamResponse" }
 
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "500":
+          $ref: "#/components/responses/ServerError"
   /directory/all_items:
     get:
       tags: [书籍]
@@ -225,6 +241,10 @@ paths:
             application/json:
               schema: { $ref: "#/components/schemas/UpstreamResponse" }
 
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "500":
+          $ref: "#/components/responses/ServerError"
   /multi-detail:
     get:
       tags: [书籍]
@@ -244,6 +264,10 @@ paths:
             application/json:
               schema: { $ref: "#/components/schemas/UpstreamResponse" }
 
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "500":
+          $ref: "#/components/responses/ServerError"
   /content:
     get:
       tags: [内容]
@@ -295,6 +319,10 @@ paths:
                             properties:
                               book_id: { type: string, description: 所属书籍 ID }
 
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "500":
+          $ref: "#/components/responses/ServerError"
   /multi-content:
     get:
       tags: [内容]
@@ -327,6 +355,10 @@ paths:
             application/json:
               schema: { $ref: "#/components/schemas/UpstreamResponse" }
 
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "500":
+          $ref: "#/components/responses/ServerError"
   /item-summary:
     get:
       tags: [内容]
@@ -346,6 +378,10 @@ paths:
             application/json:
               schema: { $ref: "#/components/schemas/UpstreamResponse" }
 
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "500":
+          $ref: "#/components/responses/ServerError"
   /chapter_review:
     get:
       tags: [评论]
@@ -371,6 +407,8 @@ paths:
         "400":
           $ref: "#/components/responses/BadRequest"
 
+        "500":
+          $ref: "#/components/responses/ServerError"
   /review:
     get:
       tags: [评论]
@@ -405,6 +443,8 @@ paths:
         "400":
           $ref: "#/components/responses/BadRequest"
 
+        "500":
+          $ref: "#/components/responses/ServerError"
   /review_html:
     get:
       tags: [评论]
@@ -432,6 +472,8 @@ paths:
         "400":
           $ref: "#/components/responses/BadRequest"
 
+        "500":
+          $ref: "#/components/responses/ServerError"
   /audio:
     get:
       tags: [多媒体]
@@ -459,6 +501,10 @@ paths:
             application/json:
               schema: { $ref: "#/components/schemas/UpstreamResponse" }
 
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "500":
+          $ref: "#/components/responses/ServerError"
   /audio/proxy/{key}:
     get:
       tags: [多媒体]
@@ -507,6 +553,10 @@ paths:
             application/json:
               schema: { $ref: "#/components/schemas/UpstreamResponse" }
 
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "500":
+          $ref: "#/components/responses/ServerError"
   /manga:
     get:
       tags: [多媒体]
@@ -547,6 +597,8 @@ paths:
         "400":
           $ref: "#/components/responses/BadRequest"
 
+        "500":
+          $ref: "#/components/responses/ServerError"
   /manga/image/{item_id}/{index}:
     get:
       tags: [多媒体]
@@ -606,6 +658,10 @@ paths:
             application/json:
               schema: { $ref: "#/components/schemas/UpstreamResponse" }
 
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "500":
+          $ref: "#/components/responses/ServerError"
   /category-landing:
     get:
       tags: [分类]
@@ -633,6 +689,10 @@ paths:
             application/json:
               schema: { $ref: "#/components/schemas/UpstreamResponse" }
 
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "500":
+          $ref: "#/components/responses/ServerError"
   /emoji/{file}:
     get:
       tags: [静态资源]
@@ -660,6 +720,7 @@ paths:
             text/plain:
               schema: { type: string }
 
+
 components:
   securitySchemes:
     accessKeyQuery:
@@ -695,6 +756,13 @@ components:
           schema:
             $ref: "#/components/schemas/ErrorResponse"
           example: { code: -1, msg: "访问被拒绝:无效的访问密钥" }
+    ServerError:
+      description: 服务端错误(上游请求失败等)
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorResponse"
+          example: { code: -1, msg: "获取内容失败: 请求超时" }
     BadRequest:
       description: 参数缺失或格式错误
       content: