CentOS 上 Swagger 性能调优指南
一 基线评估与瓶颈定位
- 明确承载形态：区分仅提供 Swagger UI 静态资源 的场景与集成在 Spring Boot + Springfox/Swagger UI 的应用场景，二者优化侧重点不同。
- 建立可观测性：采集 P95/P99 延迟、QPS、错误率、Full GC 次数/停顿、线程池队列 等指标，结合日志定位慢路径。
- 抓取热点：对 Java 应用使用 JProfiler/VisualVM 定位控制器、序列化、反射、数据库访问等瓶颈；对 UI 侧关注首屏加载与静态资源耗时。
- 设定目标：以业务可接受阈值（如 P95 < 200 ms）为优化目标，分阶段验证收益与回归风险。
二 应用层与 JVM 优化（Spring Boot 集成 Swagger 场景）
- 依赖与组件瘦身：仅保留必要的 springfox-swagger2/springfox-swagger-ui 依赖，移除未使用的 starter 与库，缩短类加载与初始化时间。
- 启动期优化：升级至较新的 Spring Boot 版本；按需调整内嵌容器线程池（如 Tomcat）参数；对 Swagger 资源按需注册，避免扫描全量包；必要时采用 延迟加载 UI 的策略，降低应用启动阶段开销。
- JVM 参数示例（Java 11+）：
- 堆大小与一致性：
-Xms4g -Xmx4g
- 低延迟 GC：
-XX:+UseZGC（或 -XX:+UseG1GC 并配合 -XX:MaxGCPauseMillis=200）
- 并行 GC 线程：
-XX:ParallelGCThreads=8
- 启用 JMX 便于排查：
-Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.port=9999 -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false
- 运行期治理：减少不必要的对象分配与反射；对 DTO/模型字段精简 降低序列化成本；将 Swagger 文档模型按需分组 与拆分，避免单次聚合过大。
三 反向代理与传输层优化（Nginx 前置示例）
- 启用压缩：开启 gzip/brotli，压缩 JSON/YAML/HTML/CSS/JS，显著降低 UI 与规范文档体积与时延。
- 浏览器与 CDN 缓存：为 /swagger-ui/、/v2/api-docs、/swagger-resources/ 等路径设置 Cache-Control: public, max-age=3600；频繁访问的 UI 资源可上 CDN。
- 连接与协议：开启 HTTP/2；合理设置 worker_processes/worker_connections；启用 TLS 会话复用 与 ECDHE 系列曲线，减少握手开销。
- 静态资源服务：将 Swagger UI 静态文件 由 Nginx 直接托管，避免穿透到后端应用。
- 示例片段：
- 启用压缩与 HTTP/2：在
nginx.conf 的 http { } 中加入 gzip on; gzip_types application/json application/javascript text/css; http2 on;
- 缓存策略：
location ~* ^/swagger-ui/|^/v2/api-docs|^/swagger-resources/ { expires 1h; add_header Cache-Control "public, max-age=3600"; }
四 数据与接口层优化
- 缓存高频访问内容：对 /v2/api-docs 等相对静态的规范内容使用 Redis/Memcached 缓存（如 TTL 5–15 分钟），并在接口/模型变更时主动失效；UI 侧配合 ETag/Last-Modified 做协商缓存。
- 减少单次返回体量：对返回大数据集的接口启用 分页/过滤/字段选择，降低序列化与网络传输压力。
- 数据库与下游依赖：为高频查询建立合适索引、优化慢 SQL；对外部服务调用设置 超时/熔断/降级，避免文档聚合或接口探测被拖慢。
五 部署架构与运行环境优化
- 水平扩展与负载均衡：多实例部署，前置 Nginx/HAProxy 做 轮询/最少连接 分发；会话保持仅在必要时启用。
- 资源与内核：为应用容器/实例配置合理 内存/CPU；使用 SSD 提升 I/O；按需调整 文件句柄数 与内核网络参数（如
net.core.somaxconn、net.ipv4.tcp_tw_reuse）。
- 监控与告警：以 Prometheus + Grafana 监控 请求时延、吞吐、错误率、JVM GC/内存 等；设置阈值告警，联动自动扩缩容与滚动重启。
- 变更与验证：优化项在 预发环境 验证后再上线；采用 灰度/金丝雀 发布，观察 P95/P99 与错误率变化，确保无回退。
