# 性能监控中间件

<cite>
**本文引用的文件**
- [performance.ts](file://server/src/middleware/performance.ts)
- [app.ts](file://server/src/app.ts)
- [logger.service.ts](file://server/src/services/logger.service.ts)
- [errorHandler.ts](file://server/src/middleware/errorHandler.ts)
- [sentry.service.ts](file://server/src/services/sentry.service.ts)
- [index.ts](file://server/src/config/index.ts)
- [OPTIMIZATION_SUMMARY.md](file://OPTIMIZATION_SUMMARY.md)
- [API.md](file://docs/API.md)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件面向AI有声书生成平台的性能监控中间件，系统性阐述其请求性能指标采集机制、存储与分析策略、配置参数与优化建议，并结合现有代码实现给出可操作的实践示例。该中间件通过Koa中间件链路对每个请求进行响应时间统计、慢请求检测与错误率统计，并提供实时指标查询接口，便于开发与运维团队快速定位性能瓶颈并进行优化。

## 项目结构
性能监控中间件位于后端服务的中间件层，与路由注册、日志与错误处理等中间件共同构成服务的运行时控制流。核心文件与职责如下：
- 性能监控中间件：负责请求耗时统计、慢请求告警、错误率统计与指标导出
- 应用入口：注册中间件顺序，挂载性能监控与指标路由
- 日志服务：提供HTTP请求日志中间件，补充请求耗时与状态信息
- 错误处理中间件：统一错误捕获，保证性能统计的完整性
- Sentry服务：提供错误与性能分析（Profiling），与性能中间件形成互补
- 配置中心：提供端口、环境等基础配置，影响监控中间件的运行环境

```mermaid
graph TB
Client["客户端"] --> Koa["Koa 应用"]
Koa --> ErrorHandler["错误处理中间件"]
Koa --> Sentry["Sentry 错误监控中间件"]
Koa --> Perf["性能监控中间件"]
Koa --> HttpLog["HTTP 日志中间件"]
Koa --> Security["安全中间件"]
Koa --> CORS["CORS 中间件"]
Koa --> BodyParser["Body 解析中间件"]
Koa --> Routes["业务路由"]
Routes --> Metrics["/api/metrics 指标查询"]
```

图表来源
- [app.ts:63-96](file://server/src/app.ts#L63-L96)
- [performance.ts:29-76](file://server/src/middleware/performance.ts#L29-L76)
- [logger.service.ts:75-102](file://server/src/services/logger.service.ts#L75-L102)
- [errorHandler.ts:3-24](file://server/src/middleware/errorHandler.ts#L3-L24)
- [sentry.service.ts:92-110](file://server/src/services/sentry.service.ts#L92-L110)

章节来源
- [app.ts:63-96](file://server/src/app.ts#L63-L96)
- [performance.ts:29-76](file://server/src/middleware/performance.ts#L29-L76)
- [logger.service.ts:75-102](file://server/src/services/logger.service.ts#L75-L102)
- [errorHandler.ts:3-24](file://server/src/middleware/errorHandler.ts#L3-L24)
- [sentry.service.ts:92-110](file://server/src/services/sentry.service.ts#L92-L110)

## 核心组件
- 性能监控中间件
  - 负责在请求进入与离开之间计算耗时，更新全局指标与端点级指标
  - 当请求耗时超过阈值（默认1秒）时输出慢请求警告
  - 在错误发生时统计错误总数与对应端点错误数
  - 提供指标读取与重置函数，以及指标查询路由
- 指标数据结构
  - 全局指标：总请求数、平均响应时间、慢请求数、错误数
  - 端点级指标：端点计数、平均耗时、最大耗时、错误数
  - 指标查询接口：返回全局指标与错误率（百分比）

章节来源
- [performance.ts:6-27](file://server/src/middleware/performance.ts#L6-L27)
- [performance.ts:29-76](file://server/src/middleware/performance.ts#L29-L76)
- [performance.ts:81-109](file://server/src/middleware/performance.ts#L81-L109)

## 架构总览
性能监控中间件在Koa应用中作为独立中间件插入，与错误处理、Sentry、HTTP日志、安全与CORS等中间件共同工作。应用启动时注册性能监控中间件与指标查询路由；业务路由处理完成后，性能中间件将当前请求耗时写入全局与端点级指标，并通过响应头返回本次请求耗时。

```mermaid
sequenceDiagram
participant C as "客户端"
participant A as "Koa 应用"
participant EH as "错误处理中间件"
participant SN as "Sentry 中间件"
participant PM as "性能监控中间件"
participant LG as "HTTP 日志中间件"
participant RT as "业务路由"
C->>A : "HTTP 请求"
A->>EH : "进入错误处理"
EH->>SN : "进入Sentry"
SN->>PM : "进入性能监控"
PM->>PM : "记录开始时间"
PM->>LG : "进入HTTP日志"
LG->>RT : "进入业务路由"
RT-->>LG : "业务处理完成"
LG-->>PM : "计算耗时并记录指标"
PM-->>C : "响应含X-Response-Time"
```

图表来源
- [app.ts:63-96](file://server/src/app.ts#L63-L96)
- [performance.ts:29-76](file://server/src/middleware/performance.ts#L29-L76)
- [logger.service.ts:75-102](file://server/src/services/logger.service.ts#L75-L102)
- [sentry.service.ts:92-110](file://server/src/services/sentry.service.ts#L92-L110)

## 详细组件分析

### 性能监控中间件类图
该中间件以函数式中间件形式存在，内部维护全局指标对象与端点级指标映射，提供指标读取、重置与查询路由。

```mermaid
classDiagram
class PerformanceMetrics {
+number totalRequests
+number avgResponseTime
+number slowRequests
+number errors
+Record~string,EndpointMetrics~ endpoints
}
class EndpointMetrics {
+number count
+number avgTime
+number maxTime
+number errors
}
class PerformanceMiddleware {
+performanceMonitor() function
+getPerformanceMetrics() function
+resetPerformanceMetrics() function
+getMetrics(ctx) function
}
PerformanceMiddleware --> PerformanceMetrics : "使用"
PerformanceMetrics --> EndpointMetrics : "包含"
```

图表来源
- [performance.ts:6-27](file://server/src/middleware/performance.ts#L6-L27)
- [performance.ts:29-76](file://server/src/middleware/performance.ts#L29-L76)
- [performance.ts:81-109](file://server/src/middleware/performance.ts#L81-L109)

章节来源
- [performance.ts:6-27](file://server/src/middleware/performance.ts#L6-L27)
- [performance.ts:29-76](file://server/src/middleware/performance.ts#L29-L76)
- [performance.ts:81-109](file://server/src/middleware/performance.ts#L81-L109)

### 指标计算流程
- 请求进入：记录起始时间，构造端点标识（方法+路径），初始化端点指标
- 正常返回：计算耗时，更新全局与端点级指标；若超过慢请求阈值则记录慢请求并输出警告；向响应头写入X-Response-Time
- 异常抛出：统计错误总数与端点错误数，交由错误处理中间件统一处理

```mermaid
flowchart TD
Start(["请求进入"]) --> Init["初始化端点指标"]
Init --> TryNext["调用下游中间件/路由"]
TryNext --> Calc["计算耗时"]
Calc --> UpdateGlobal["更新全局指标<br/>总请求数/平均耗时/慢请求数"]
UpdateGlobal --> UpdateEndpoint["更新端点指标<br/>计数/平均耗时/最大耗时"]
UpdateEndpoint --> SlowCheck{"是否慢请求?"}
SlowCheck --> |是| Warn["输出慢请求警告"]
SlowCheck --> |否| SetHeader["设置响应头 X-Response-Time"]
Warn --> SetHeader
SetHeader --> Return(["返回响应"])
TryNext --> |异常| IncErr["统计错误总数与端点错误数"] --> Throw["抛出错误给错误处理中间件"]
```

图表来源
- [performance.ts:29-76](file://server/src/middleware/performance.ts#L29-L76)

章节来源
- [performance.ts:29-76](file://server/src/middleware/performance.ts#L29-L76)

### 指标查询路由序列图
- 客户端请求GET /api/metrics
- 应用路由匹配到指标查询函数
- 指标查询函数返回包含全局指标与错误率的数据体

```mermaid
sequenceDiagram
participant Client as "客户端"
participant Router as "Koa 路由"
participant Ctrl as "指标控制器(getMetrics)"
participant Perf as "性能中间件"
Client->>Router : "GET /api/metrics"
Router->>Ctrl : "调用 getMetrics(ctx)"
Ctrl->>Perf : "读取性能指标"
Perf-->>Ctrl : "返回指标快照"
Ctrl-->>Client : "JSON 响应包含错误率"
```

图表来源
- [app.ts:95-96](file://server/src/app.ts#L95-L96)
- [performance.ts:99-109](file://server/src/middleware/performance.ts#L99-L109)

章节来源
- [app.ts:95-96](file://server/src/app.ts#L95-L96)
- [performance.ts:99-109](file://server/src/middleware/performance.ts#L99-L109)

### 与其他中间件的协作关系
- 错误处理中间件：在性能中间件之后执行，确保异常被统一捕获并返回标准错误格式
- Sentry中间件：在性能中间件之前执行，负责错误与性能分析（Profiling），与性能中间件形成互补
- HTTP日志中间件：在性能中间件之后执行，基于性能中间件提供的耗时信息记录HTTP请求日志
- 安全与CORS中间件：在性能中间件之前执行，保障请求安全与跨域访问

章节来源
- [app.ts:63-82](file://server/src/app.ts#L63-L82)
- [errorHandler.ts:3-24](file://server/src/middleware/errorHandler.ts#L3-L24)
- [logger.service.ts:75-102](file://server/src/services/logger.service.ts#L75-L102)
- [sentry.service.ts:92-110](file://server/src/services/sentry.service.ts#L92-L110)

## 依赖关系分析
- 性能监控中间件依赖Koa上下文与next回调，通过中间件链路实现非侵入式统计
- 指标查询路由依赖性能中间件提供的指标读取函数
- 日志中间件依赖性能中间件提供的耗时信息，形成统一的HTTP日志
- Sentry中间件与性能中间件相互独立，分别负责错误与性能分析

```mermaid
graph LR
PM["性能监控中间件"] --> CTX["Koa 上下文"]
PM --> NEXT["next 回调"]
PM --> METRICS["指标对象"]
METRICS --> GLOBAL["全局指标"]
METRICS --> ENDPOINT["端点指标"]
ROUTER["应用路由"] --> GETMETRICS["getMetrics 控制器"]
GETMETRICS --> PM
LOG["HTTP 日志中间件"] --> PM
ERR["错误处理中间件"] --> PM
SEN["Sentry 中间件"] -.-> PM
```

图表来源
- [performance.ts:29-76](file://server/src/middleware/performance.ts#L29-L76)
- [performance.ts:99-109](file://server/src/middleware/performance.ts#L99-L109)
- [logger.service.ts:75-102](file://server/src/services/logger.service.ts#L75-L102)
- [app.ts:95-96](file://server/src/app.ts#L95-L96)

章节来源
- [performance.ts:29-76](file://server/src/middleware/performance.ts#L29-L76)
- [performance.ts:99-109](file://server/src/middleware/performance.ts#L99-L109)
- [logger.service.ts:75-102](file://server/src/services/logger.service.ts#L75-L102)
- [app.ts:95-96](file://server/src/app.ts#L95-L96)

## 性能考量
- 指标粒度与开销
  - 全局与端点级指标均为内存态聚合，适合中小规模并发；在高并发场景建议结合外部时序数据库或指标系统进行持久化与聚合
- 慢请求阈值
  - 默认阈值为1秒，可根据业务特性调整；建议在不同环境采用差异化阈值
- 错误率统计
  - 错误率通过全局错误数与总请求数计算，便于快速评估系统健康度
- 响应头透传
  - 将X-Response-Time写入响应头，便于前端与网关侧进行端到端耗时分析
- 与其他监控的协同
  - 性能中间件关注请求层面的耗时与错误；Sentry提供更细粒度的错误追踪与性能分析（Profiling），二者结合可覆盖端到端性能画像

章节来源
- [performance.ts:27](file://server/src/middleware/performance.ts#L27)
- [performance.ts:104-106](file://server/src/middleware/performance.ts#L104-L106)
- [sentry.service.ts:15-22](file://server/src/services/sentry.service.ts#L15-L22)

## 故障排查指南
- 指标为空或不更新
  - 确认性能监控中间件已在应用入口正确注册且位于路由之前
  - 检查是否存在上游中间件提前终止请求导致未进入性能中间件
- 慢请求告警频繁
  - 结合端点级指标定位具体慢接口，分析下游依赖（数据库、第三方服务）是否异常
  - 调整慢请求阈值以适配业务峰值
- 错误率异常升高
  - 使用错误处理中间件返回的标准错误格式定位错误来源
  - 结合Sentry中间件的Profiling能力进行深度分析
- 指标查询接口异常
  - 确认路由已注册到/api/metrics
  - 检查控制器函数是否正确返回指标快照

章节来源
- [app.ts:63-96](file://server/src/app.ts#L63-L96)
- [errorHandler.ts:3-24](file://server/src/middleware/errorHandler.ts#L3-L24)
- [sentry.service.ts:92-110](file://server/src/services/sentry.service.ts#L92-L110)
- [performance.ts:99-109](file://server/src/middleware/performance.ts#L99-L109)

## 结论
该性能监控中间件以轻量、非侵入的方式实现了请求级性能指标采集与慢请求告警，配合指标查询接口与HTTP日志中间件，能够满足日常性能观测需求。在生产环境中，建议结合Sentry的Profiling能力与外部指标系统，进一步完善性能数据的持久化、聚合与可视化，从而实现从“可观测”到“可优化”的闭环。

## 附录

### 性能配置参数与优化建议
- 慢请求阈值
  - 当前默认1000毫秒，可在中间件中调整阈值以适配不同业务场景
- 采样率与聚合
  - 内部指标为全量统计；如需降低开销，可考虑引入采样策略或外部时序数据库进行周期性聚合
- 告警阈值
  - 错误率与慢请求数可用于设置告警阈值；建议在不同环境采用差异化阈值
- 指标导出
  - 通过GET /api/metrics获取当前指标快照，便于集成到监控面板或自动化告警系统

章节来源
- [performance.ts:27](file://server/src/middleware/performance.ts#L27)
- [performance.ts:99-109](file://server/src/middleware/performance.ts#L99-L109)

### 实际性能监控示例
- 启用性能跟踪
  - 在应用入口注册性能监控中间件与指标查询路由
- 查看性能报告
  - 访问GET /api/metrics，查看全局指标与错误率
- 优化建议
  - 结合端点级指标定位慢接口，优化数据库查询或第三方依赖
  - 使用Sentry Profiling能力进行热点函数分析

章节来源
- [app.ts:63-96](file://server/src/app.ts#L63-L96)
- [performance.ts:99-109](file://server/src/middleware/performance.ts#L99-L109)
- [OPTIMIZATION_SUMMARY.md:332-342](file://OPTIMIZATION_SUMMARY.md#L332-L342)