✨ feat(api): 统一响应格式并完善参数体系与文档

- 正文参数支持语义值(plain/html/keep/remove)与别名(img_mode/review_mode)，URL 参数优先于配置
- 修复纯文本被段评强制包回 HTML、HTML 模式段评注入失效的问题
- 修复 PKCS7 填充弱校验导致漫画/正文偶发解密乱码返回 200 的问题
- 搜索结果展平：去 search_tabs 层与 selected_tab_idx/server_ab_params，提升 has_more/next_offset
- 全接口解包字符串形式的 JSON 字段(category_schema 等)，缓存出口幂等处理
- 序列化关闭 HTML 转义，video/audio 播放链接可直接复制播放
- video 响应透传 CENC 加密状态(key_seed/kid/encryption_method)
- 新增 gzip 中间件，JSON/文本响应压缩约 81%，二进制透传
- 漫画默认输出模式改为 proxy(url 模式链接 404 且内容加密不可用)
- openapi.yaml：补全 23 个路径参数定义、tab_type 完整枚举、CDN 签名说明，示例更新

internal/handlers/common.go

@@ -103,6 +103,14 @@ func StopStatisticsSaver() {
 	}
 }
 
+// getQueryWithAlias 读 URL 参数，主名未传时回退到别名（兼容 README 历史参数名）
+func getQueryWithAlias(r *http.Request, name, alias string) string {
+	if v := r.URL.Query().Get(name); v != "" {
+		return v
+	}
+	return r.URL.Query().Get(alias)
+}
+
 // respondError 统一错误响应（JSON 安全编码；isClientErr 为 true 时返回 400，否则 500）
 func respondError(w http.ResponseWriter, msg string, isClientErr bool) {
 	status := http.StatusInternalServerError

internal/handlers/content.go

@@ -19,10 +19,10 @@ func HandleContent(w http.ResponseWriter, r *http.Request) {
 	}
 	itemID := params["item_id"]
 
-	// 获取URL参数（支持动态覆盖配置）
-	textMode := r.URL.Query().Get("text_mode")   // 1=纯文本模式
-	imageMode := r.URL.Query().Get("image_mode") // 0=移除图片, 1=保留图片
-	reviewParam := r.URL.Query().Get("review")   // 1=启用段评, 0=禁用段评
+	// 获取URL参数（支持动态覆盖配置；image_mode/review 兼容 README 的 img_mode/review_mode 别名）
+	textMode := r.URL.Query().Get("text_mode") // plain/1=纯文本, html/0=HTML
+	imageMode := getQueryWithAlias(r, "image_mode", "img_mode")
+	reviewParam := getQueryWithAlias(r, "review", "review_mode") // keep/1=启用段评, remove/0=禁用段评
 
 	result, err := fqapi.HandleGetContent(itemID, textMode, imageMode)
 	if err != nil {
@@ -32,17 +32,15 @@ func HandleContent(w http.ResponseWriter, r *http.Request) {
 
 	// 判断是否启用段评功能
 	// 优先使用URL参数，如果没有则使用配置文件
-	enableReview := false
-	if reviewParam == "1" {
-		enableReview = true
-	} else if reviewParam == "0" {
-		enableReview = false
-	} else {
+	var enableReview bool
+	if reviewParam == "" {
 		// 没有URL参数时，使用配置文件
 		cfg := config.GetConfig()
 		if cfg != nil {
 			enableReview = cfg.Fanqie.Content.EnableReview
 		}
+	} else {
+		enableReview = fqapi.ParseBoolParam(reviewParam)
 	}
 
 	// 如果启用了段评功能，处理正文内容添加段评标记
@@ -65,7 +63,7 @@ func HandleMultiContent(w http.ResponseWriter, r *http.Request) {
 	}
 
 	textMode := r.URL.Query().Get("text_mode")
-	imageMode := r.URL.Query().Get("image_mode")
+	imageMode := getQueryWithAlias(r, "image_mode", "img_mode")
 	ignoreFailed := r.URL.Query().Get("ignore_failed")
 
 	result, err := fqapi.HandleMultiContent(params["item_ids"], params["book_id"], textMode, imageMode, ignoreFailed)

internal/handlers/gzip.go

@@ -0,0 +1,74 @@
+package handlers
+
+import (
+	"compress/gzip"
+	"net/http"
+	"strings"
+)
+
+// Gzip 对 JSON/文本响应启用 gzip 压缩（仅客户端声明 Accept-Encoding: gzip 时）。
+// 图片/音频等二进制响应不在白名单内，原样透传。
+func Gzip(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if !strings.Contains(r.Header.Get("Accept-Encoding"), "gzip") {
+			next.ServeHTTP(w, r)
+			return
+		}
+		gw := &gzipWriter{ResponseWriter: w}
+		defer gw.close()
+		next.ServeHTTP(gw, r)
+	})
+}
+
+type gzipWriter struct {
+	http.ResponseWriter
+	zw         *gzip.Writer
+	decided    bool // 是否已根据 Content-Type 做过压缩决定
+	headerSent bool
+}
+
+func (g *gzipWriter) WriteHeader(status int) {
+	if g.headerSent {
+		return
+	}
+	if !g.decided {
+		g.decide()
+	}
+	g.ResponseWriter.WriteHeader(status)
+	g.headerSent = true
+}
+
+func (g *gzipWriter) Write(b []byte) (int, error) {
+	if !g.headerSent {
+		// handler 未显式 WriteHeader（fmt.Fprint 直接写）时的隐式 200
+		if !g.decided {
+			g.decide()
+		}
+		g.ResponseWriter.WriteHeader(http.StatusOK)
+		g.headerSent = true
+	}
+	if g.zw != nil {
+		return g.zw.Write(b)
+	}
+	return g.ResponseWriter.Write(b)
+}
+
+// decide 在首个响应头确定时判断是否压缩（此时 handler 已设置 Content-Type）
+func (g *gzipWriter) decide() {
+	g.decided = true
+	ct := g.Header().Get("Content-Type")
+	for _, prefix := range []string{"application/json", "text/html", "text/plain"} {
+		if strings.HasPrefix(ct, prefix) {
+			g.Header().Set("Content-Encoding", "gzip")
+			g.Header().Del("Content-Length")
+			g.zw = gzip.NewWriter(g.ResponseWriter)
+			return
+		}
+	}
+}
+
+func (g *gzipWriter) close() {
+	if g.zw != nil {
+		g.zw.Close()
+	}
+}