如何在Ktor WebSocket Server中发送自定义Header供客户端OnOpen回调获取？

核心原理 #

WebSocket 连接基于 HTTP 握手升级建立，客户端的onOpen回调只能获取握手阶段的HTTP响应头。因此要让客户端在onOpen中捕获自定义Header，必须在握手响应中添加这些头，而非后续的WebSocket帧里。

具体实现步骤 #

1. 在Ktor服务端握手响应中添加自定义Header #

在webSocket路由处理块的最开始，通过call.response.headers直接添加自定义响应头，确保在握手完成前发送给客户端：

install(WebSockets)

routing {
    webSocket("/ws") {
        // 添加自定义响应头，必须在握手完成前执行
        call.response.headers.append("X-Custom-Header", "your-custom-value")
        call.response.headers.append("X-User-ID", "12345") // 可添加多个自定义头

        // 后续处理WebSocket消息逻辑
        for (frame in incoming) {
            when (frame) {
                is Frame.Text -> {
                    val receivedText = frame.readText()
                    outgoing.send(Frame.Text("Received: $receivedText"))
                }
                else -> {}
            }
        }
    }
}

2. 客户端在onOpen中捕获自定义Header #

以浏览器原生WebSocket为例，在onOpen事件中直接读取响应头：

const ws = new WebSocket('ws://localhost:8080/ws');

ws.onopen = (event) => {
    const customHeader = event.target.headers.get('X-Custom-Header');
    const userId = event.target.headers.get('X-User-ID');
    console.log('自定义Header:', customHeader, userId);
};

跨域场景注意：部分浏览器会限制跨域响应头的访问，需在Ktor服务端配置CORS暴露自定义头：

install(CORS) {
    anyHost()
    exposeHeader("X-Custom-Header")
    exposeHeader("X-User-ID")
}

3. 连接建立后动态传递"Header"的替代方案 #

若需在连接建立后发送动态变化的自定义标识，此时HTTP握手已完成，无法修改响应头。可通过自定义消息格式传递：

• 服务端发送结构化消息：

val dynamicHeaderMsg = """{"type":"header","data":{"X-Dynamic-Token":"updated-token-789"}}"""
outgoing.send(Frame.Text(dynamicHeaderMsg))

• 客户端解析处理：

ws.onmessage = (event) => {
    try {
        const data = JSON.parse(event.data);
        if (data.type === 'header') {
            console.log('动态自定义标识:', data.data);
        } else {
            console.log('收到普通消息:', data);
        }
    } catch (e) {
        console.log('收到文本消息:', event.data);
    }
};

内容的提问来源于stack exchange，提问作者Ali Zarei