REST API 请求日志记录与 RAW 请求分析指南

一. REST API 请求日志记录概述

在开发 REST API 时，记录请求日志是必不可少的环节。尤其在调试和问题排查过程中，完整的请求日志能够帮助开发者快速定位问题。本文将结合实际案例，讲解如何捕获和记录完整的 RAW 请求消息及响应内容，以便更高效地分析和解决问题。

二. 遇到的问题

在进行第一个 REST 操作时，我尝试向网络中的内部服务器发送 API 请求。虽然 SSL/TLS（安全套接字层/传输层安全）配置成功，但仍遇到如下错误：

ERRORErrHTTPStatus: 从远程 HTTP 服务器接收到非正常状态 403：“HTTP/1.1 403 Forbidden”。

为排查问题，我尝试使用 $$$TRACE 捕获操作中发送的各类元素，包括服务器、URL、SSL 配置和请求负载。然而，导致 403 错误 的具体原因仍未明确。

三. 如何查看 RAW 请求消息

为了深入分析问题，需要查看完整的 RAW 请求消息，包括 Header 与 Data 元素。以下方法可以帮助实现这一目标：

1. 使用 POSTMAN 验证请求

在 POSTMAN 中可以清楚查看请求内容，例如：

POST xxxxxxxxxxxxxxx

{
  "患者ID": "x",
  "患者IDType": "xxxxxxx",
  "ContactID": "x",
  "ContactIDType": "xxxx",
  "用户ID": "xxxxx",
  "用户IDType": "xxxxxxxxxx"
}

通过 POSTMAN 验证，可以确认请求内容与操作中使用的变量一致，从而排除请求构造错误的可能性。

2. 捕获 RAW 请求消息

在实际操作中，可以通过跟踪查看器记录完整的 RAW 请求消息，帮助分析 Header 和 Data 是否正确：

a. 启用跟踪日志

利用 InterSystems 提供的工具启用跟踪日志，将请求的 Header 和 Data 记录下来。

b. 检查 SSL/TLS 配置

确保 SSL/TLS 配置无误，避免安全协议问题导致请求被拒绝。

c. 记录完整响应

除了请求消息，还应记录服务器返回的完整响应内容，以便准确定位问题根源。

四. 服务器返回的响应示例

以下是服务器返回的响应示例：

{
  "消息": "执行命令时出错：NO-PATIENT-FOUND details：找不到具有提供的ID和ID类型的患者..",
  "ExceptionMessage": "在执行命令时发生错误：NO-PATIENT-FOUND details: 找不到带有提供的ID和ID类型的患者..",
  "ExceptionType": "System.Web.HttpException",
  "StackTrace": null
}

从响应中可以看出，服务器明确指出问题原因：提供的患者 ID 与 ID 类型不匹配，提示请求中可能缺少必要的标识符或参数。

五. 总结与建议

在调试 REST API 请求时，记录完整的 RAW 请求消息和响应内容至关重要。关键建议如下：

使用调试工具
通过 POSTMAN 或类似工具，验证请求内容是否符合预期。
启用日志记录
利用 InterSystems 跟踪查看器，记录请求的 Header 与 Data 元素。
检查配置
确保服务器地址、SSL/TLS 配置和请求参数正确无误。
分析响应
根据服务器返回的错误信息，准确定位问题原因。

通过上述方法，可以高效排查问题并优化 REST API 请求流程。

原文链接: https://community.intersystems.com/post/rest-api-request-logging