Spring Boot HTTP 交换记录 📝

概述

在现代微服务架构中，HTTP 请求和响应的监控与记录是系统可观测性的重要组成部分。Spring Boot 提供了 HTTP Exchange Recording 功能，让我们能够轻松记录和查看应用程序的 HTTP 交互历史。

NOTE

HTTP Exchange Recording 是 Spring Boot Actuator 的一部分，主要用于开发和调试阶段，帮助开发者了解应用程序的 HTTP 交互情况。

为什么需要 HTTP 交换记录？ 🤔

在没有 HTTP 交换记录功能之前，开发者面临以下痛点：

调试困难：无法快速查看最近的 HTTP 请求和响应详情
问题排查复杂：当出现问题时，需要通过日志文件逐行查找相关信息
性能分析不便：难以直观了解请求的处理时间和状态
接口测试繁琐：需要额外的工具来监控 API 调用情况

HTTP Exchange Recording 功能的出现，正是为了解决这些开发和运维中的实际问题。

核心组件解析

HttpExchangeRepository 接口

HttpExchangeRepository 是 HTTP 交换记录的核心接口，负责存储和检索 HTTP 交换信息。

kotlin

// Spring Boot 内置的内存实现
@Configuration
class HttpExchangeConfig {
    
    @Bean
    fun httpExchangeRepository(): HttpExchangeRepository {
        // 默认存储最近 100 次请求-响应交换
        return InMemoryHttpExchangeRepository()
    }
}

工作原理时序图

快速上手实践

1. 基础配置

首先，在你的 Spring Boot 项目中启用 HTTP 交换记录：

基础配置application.yml

kotlin

@SpringBootApplication
@EnableWebMvc
class Application

@Configuration
class ActuatorConfig {
    
    @Bean
    fun httpExchangeRepository(): HttpExchangeRepository {
        return InMemoryHttpExchangeRepository().apply {
            // 可以设置容量，默认是 100
            setCapacity(200) 
        }
    }
}

yaml

management:
  endpoints:
    web:
      exposure:
        include: httpexchanges
  httpexchanges:
    recording:
      enabled: true
      include: # 自定义记录内容
        - request-headers
        - response-headers
        - cookie-headers
        - time-taken

2. 创建测试控制器

kotlin

@RestController
@RequestMapping("/api")
class TestController {
    
    @GetMapping("/hello")
    fun hello(@RequestParam name: String = "World"): Map<String, Any> {
        return mapOf(
            "message" to "Hello, $name!",
            "timestamp" to System.currentTimeMillis()
        )
    }
    
    @PostMapping("/users")
    fun createUser(@RequestBody user: User): ResponseEntity<User> {
        // 模拟用户创建逻辑
        val createdUser = user.copy(id = (1..1000).random())
        return ResponseEntity.status(HttpStatus.CREATED).body(createdUser) 
    }
}

data class User(
    val id: Int? = null,
    val name: String,
    val email: String
)

3. 测试和查看记录

启动应用后，进行一些 HTTP 请求：

bash

# 发送 GET 请求
curl "http://localhost:8080/api/hello?name=Spring"

# 发送 POST 请求
curl -X POST "http://localhost:8080/api/users" \
  -H "Content-Type: application/json" \
  -d '{"name":"张三","email":"[email protected]"}'

# 查看交换记录
curl "http://localhost:8080/actuator/httpexchanges"

自定义配置详解

记录内容定制

通过配置文件可以精确控制记录哪些信息：

yaml

management:
  httpexchanges:
    recording:
      include:
        - request-headers      # 请求头
        - response-headers     # 响应头
        - cookie-headers       # Cookie 信息
        - authorization-header # 授权头（注意安全性）
        - remote-address      # 客户端地址
        - session-id          # 会话 ID
        - principal           # 认证主体
        - time-taken          # 处理时间

WARNING

记录 authorization-header 可能会暴露敏感信息，在生产环境中需要谨慎使用。

自定义 HttpExchangeRepository

对于生产环境，你可能需要实现自己的存储策略：

自定义存储实现示例

kotlin

@Component
class DatabaseHttpExchangeRepository(
    private val jdbcTemplate: JdbcTemplate
) : HttpExchangeRepository {
    
    override fun findAll(): List<HttpExchange> {
        val sql = """
            SELECT request_method, request_uri, response_status, 
                   request_headers, response_headers, time_taken, created_at
            FROM http_exchanges 
            ORDER BY created_at DESC 
            LIMIT 100
        """.trimIndent()
        
        return jdbcTemplate.query(sql) { rs, _ ->
            // 构建 HttpExchange 对象
            createHttpExchange(rs)
        }
    }
    
    override fun add(httpExchange: HttpExchange) {
        val sql = """
            INSERT INTO http_exchanges 
            (request_method, request_uri, response_status, 
             request_headers, response_headers, time_taken, created_at)
            VALUES (?, ?, ?, ?, ?, ?, ?)
        """.trimIndent()
        
        jdbcTemplate.update(sql,
            httpExchange.request.method,
            httpExchange.request.uri.toString(),
            httpExchange.response?.status?.value(),
            // 序列化 headers
            serializeHeaders(httpExchange.request.headers),
            serializeHeaders(httpExchange.response?.headers),
            httpExchange.timeTaken?.toMillis(),
            Instant.now()
        )
    }
    
    private fun serializeHeaders(headers: MultiValueMap<String, String>?): String {
        return headers?.let { 
            ObjectMapper().writeValueAsString(it) 
        } ?: "{}"
    }
    
    private fun createHttpExchange(rs: ResultSet): HttpExchange {
        // 实现从 ResultSet 构建 HttpExchange 的逻辑
        // 这里简化处理，实际需要完整实现
        TODO("实现 HttpExchange 构建逻辑")
    }
}

实际应用场景

场景 1：API 调试和测试

kotlin

@RestController
class OrderController {
    
    @PostMapping("/orders")
    fun createOrder(@RequestBody order: CreateOrderRequest): ResponseEntity<Order> {
        try {
            val createdOrder = orderService.createOrder(order)
            return ResponseEntity.ok(createdOrder) 
        } catch (ex: ValidationException) {
            return ResponseEntity.badRequest().build() 
        }
    }
}

通过 /actuator/httpexchanges 端点，你可以快速查看：

请求参数是否正确传递
响应状态码和内容
请求处理时间

场景 2：性能监控

kotlin

@Configuration
class PerformanceMonitoringConfig {
    
    @Bean
    fun performanceHttpExchangeRepository(): HttpExchangeRepository {
        return object : InMemoryHttpExchangeRepository() {
            override fun add(httpExchange: HttpExchange) {
                super.add(httpExchange)
                
                // 监控慢请求
                httpExchange.timeTaken?.let { duration ->
                    if (duration.toMillis() > 1000) { // 超过 1 秒
                        logger.warn("慢请求检测: ${httpExchange.request.uri} 耗时 ${duration.toMillis()}ms")
                    }
                }
            }
        }
    }
    
    companion object {
        private val logger = LoggerFactory.getLogger(PerformanceMonitoringConfig::class.java)
    }
}

最佳实践与注意事项

✅ 推荐做法

开发环境使用：主要在开发和测试环境中启用
合理设置容量：根据需要调整记录数量，避免内存溢出
选择性记录：只记录必要的信息，减少性能影响

kotlin

@Configuration
@Profile("dev", "test") // 只在开发和测试环境启用
class DevHttpExchangeConfig {
    
    @Bean
    fun httpExchangeRepository(): HttpExchangeRepository {
        return InMemoryHttpExchangeRepository().apply {
            setCapacity(50) // 开发环境较小容量即可
        }
    }
}

⚠️ 注意事项

CAUTION

生产环境谨慎使用：InMemoryHttpExchangeRepository 会消耗内存，在高并发的生产环境中可能影响性能。

IMPORTANT

安全考虑：避免记录敏感信息如密码、令牌等。可以通过自定义过滤器排除敏感头部。

kotlin

@Configuration
class SecurityAwareHttpExchangeConfig {
    
    @Bean
    fun secureHttpExchangeRepository(): HttpExchangeRepository {
        return object : InMemoryHttpExchangeRepository() {
            override fun add(httpExchange: HttpExchange) {
                // 过滤敏感信息
                val sanitizedExchange = sanitizeExchange(httpExchange)
                super.add(sanitizedExchange)
            }
            
            private fun sanitizeExchange(exchange: HttpExchange): HttpExchange {
                // 移除敏感头部信息
                // 实现敏感信息过滤逻辑
                return exchange
            }
        }
    }
}

总结

Spring Boot 的 HTTP Exchange Recording 功能为开发者提供了一个简单而强大的工具来监控和调试 HTTP 交互。通过合理配置和使用，它能够显著提升开发效率和问题排查能力。

关键要点回顾

开发利器：主要用于开发和调试阶段
灵活配置：可以自定义记录内容和存储策略
安全第一：注意过滤敏感信息
性能考虑：生产环境建议使用专业的链路追踪方案

记住，这个功能的核心价值在于让 HTTP 交互变得"可见"，从而帮助我们更好地理解和优化我们的应用程序！ 🎉

原生镜像

容器镜像

Spring Boot HTTP 交换记录 📝

概述

为什么需要 HTTP 交换记录？ 🤔

核心组件解析

HttpExchangeRepository 接口

工作原理时序图

快速上手实践

1. 基础配置

2. 创建测试控制器

3. 测试和查看记录

自定义配置详解

记录内容定制

自定义 HttpExchangeRepository

实际应用场景

场景 1：API 调试和测试

场景 2：性能监控

最佳实践与注意事项

✅ 推荐做法

⚠️ 注意事项

总结

Spring Boot HTTP 交换记录 📝 ​

概述 ​

为什么需要 HTTP 交换记录？ 🤔 ​

核心组件解析 ​

HttpExchangeRepository 接口 ​

工作原理时序图 ​

快速上手实践 ​

1. 基础配置 ​

2. 创建测试控制器 ​

3. 测试和查看记录 ​

自定义配置详解 ​

记录内容定制 ​

自定义 HttpExchangeRepository ​

实际应用场景 ​

场景 1：API 调试和测试 ​

场景 2：性能监控 ​

最佳实践与注意事项 ​

✅ 推荐做法 ​

⚠️ 注意事项 ​

总结 ​

Spring Boot HTTP 交换记录 📝

概述

为什么需要 HTTP 交换记录？ 🤔

核心组件解析

HttpExchangeRepository 接口

工作原理时序图

快速上手实践

1. 基础配置

2. 创建测试控制器

3. 测试和查看记录

自定义配置详解

记录内容定制

自定义 HttpExchangeRepository

实际应用场景

场景 1：API 调试和测试

场景 2：性能监控

最佳实践与注意事项

✅ 推荐做法

⚠️ 注意事项

总结