准确掌握API接口实际执行耗时需采用无侵入埋点机制：一、全局中间件计时；二、数据库查询事件监听；三、Prometheus直方图打点；四、手动代码块级microtime；五、内置Trace调试；六、Swoole/RoadRunner异步日志。
如果您在ThinkPHP项目中需要准确掌握API接口的实际执行耗时，但现有日志或调试工具无法提供真实请求生命周期的毫秒级数据，则可能是由于缺乏统一、无侵入的埋点机制。以下是记录API耗时的多种可行方法：
一、全局中间件埋点计时
该方法通过PSR-15中间件在请求进入和响应发出的边界处记录时间戳，确保覆盖所有HTTP请求路径（含404、500等异常分支），且不干扰业务逻辑与JSON输出格式。
1、在app/middleware/PerformanceRecord.php中定义中间件类，确保handle()方法接收$request和$next参数。
2、在handle()开头调用$start = microtime(true)获取浮点秒级起始时间。
立即学习“PHP免费学习笔记（深入）”；
3、执行$response = $next($request)将控制权交予后续中间件及控制器。
4、在handle()末尾计算耗时：$cost_ms = round((microtime(true) - $start) * 1000, 2)。
5、使用think\facade\Log::info()写入结构化日志，包含uri、method、status_code和cost_ms字段。
6、必须关闭APP_DEBUG模式，否则Debugbar等调试组件会引入额外20–50ms开销，导致基线失真。
二、数据库查询事件监听补全SQL耗时
仅统计总请求耗时不足够，因SQL执行常占整体耗时60%以上；此方法通过框架事件机制捕获每条查询的精确执行时间，弥补中间件总耗时中缺失的数据库环节细节。
1、在app/provider/EventServiceProvider.php的listen数组中添加think\db\Events\Querying::class => [app\listener\LogQueryTime::class]。
2、创建app/listener/LogQueryTime.php，实现handle()方法，在其中调用microtime(true)记录查询发起时刻。
3、监听think\db\Events\Queried::class事件，在其处理器中再次调用microtime(true)并计算差值。
4、将SQL语句、绑定参数、执行毫秒数、堆栈位置写入独立日志通道（如query_slow.log）。
5、避免使用Db::getQueryTime()直接获取，因其返回的是最后一次查询耗时，无法与当前请求URI关联，且不包含连接建立、结果集解析等环节。
三、Prometheus直方图指标打点
面向生产环境可观测性需求，该方法将API耗时以直方图形式暴露为标准Prometheus指标，配合Grafana可实现P90/P95延迟趋势分析与告警联动。
1、执行composer require prometheus/client_php安装客户端扩展。
2、新建中间件app/middleware/PrometheusMiddleware.php，在__construct()中初始化单例Prometheus\CollectorRegistry::getDefault()。
3、定义响应时间直方图指标tp_api_response_time_seconds，预设buckets为[0.01, 0.05, 0.1, 0.25, 0.5, 1, 2]（单位：秒）。
4、在handle()结尾调用$histogram->observe($duration)，其中$duration为(microtime(true) - $start)的原始浮点值。
5、清洗label值：禁止使用Request::url()作为path label，应改用Route::getRule()并替换动态参数为占位符（如/user/{id}）。
四、手动代码块级microtime打点
针对关键业务逻辑段（如第三方API调用、文件处理、加密解密），需脱离请求生命周期粒度，进行细粒度耗时定位，适用于问题复现后快速验证瓶颈模块。
1、在控制器或服务类方法内目标代码块前插入$block_start = microtime(true)。
2、在代码块结束后立即插入$block_cost = round((microtime(true) - $block_start) * 1000, 2)。
3、调用Log::debug('block_perf', ['section' => 'third_party_call', 'cost_ms' => $block_cost])写入调试日志。
4、严禁在打点前后使用dump()、echo或exit()，否则会导致JSON响应格式破坏或中断请求流程。
5、对高频调用的方法，应封装为复用工具函数（如Stopwatch::start('section_name')与Stopwatch::end('section_name')）。
五、利用ThinkPHP内置Trace调试功能
专用于开发环境快速诊断，无需编码即可可视化展示SQL耗时、模板渲染、文件加载及总耗时分解，适合本地联调阶段即时反馈性能构成。
1、确保APP_DEBUG = true且app_trace = true在.env中启用。
2、访问任意API接口时，在HTTP响应头中检查是否存在X-Think-Trace字段，或在页面底部查看Trace面板。
3、点击“SQL”标签页查看每条查询的执行时间、影响行数及参数绑定详情。
4、切换至“系统”标签页，确认“总运行时间”是否与预期一致，并比对“内存消耗”增长幅度。
5、禁止在生产环境开启trace功能，因其会显著增加CPU与内存开销，并暴露敏感路径与SQL结构。
六、Swoole/RoadRunner环境下异步日志写入
当ThinkPHP部署于Swoole常驻进程或RoadRunner容器中时，同步日志写入会阻塞Worker协程，降低吞吐量；本方法通过协程安全的日志通道保障计时精度与I/O隔离。
1、确认已启用Swoole协程：Swoole\Coroutine::set(['hook_flags' => SWOOLE_HOOK_ALL])。
2、在全局中间件handle()末尾，不直接调用Log::info()，而改用Swoole\Coroutine::create()启动新协程。
3、新协程内执行日志写入操作，确保主协程不受磁盘I/O影响。
4、若使用RoadRunner，配置logs插件启用异步通道，并将性能日志路由至专用perf.log文件。
5、microtime(true)在Swoole中仍完全可靠，但必须避免在协程切换点（如co::sleep()）前后读取，以防时间戳跨协程错乱。
