JsonStream一道面试题衍生的 TCP JSON 帧协议库

自定义二进制帧协议承载 JSON，一条 TCP 连接上跑请求/响应、流式、双工、单向、发布/订阅五种交互。心跳、断线恢复、压缩加密、credit 背压都在协议内，不靠应用层自造。Go 参考实现纯标准库、零第三方依赖；协议规范语言无关，其他语言实现规划中。

协议规范（单一事实源）

上手指南

从 go get 到五种交互模式跑通一遍，每段代码对照真实 API，可直接运行。

开始使用

面试题要求

题面原文分组归档，逐条对照实现现状：完成了标依据，做了取舍就说理由。

题面与现状

协议规范

语言无关的单一事实源：帧格式逐字段、握手协商、交互原语、错误码表、变换管线、背压与恢复。只拿这一份就应能写出可互通的实现。

阅读规范

API 参考

Go 参考实现的全部公开 API：入口、五种交互的发起与响应端、Config 逐字段默认值、帧层与错误码表。

查阅 API

与 WebSocket 对照

WS 有我们没有的（浏览器原生可达、TLS 一等承载），也有没有我们内建的（req/res、pub/sub、背压、恢复）。分片已定稿为独立 FRAGMENT 帧型，实现落地中。每条对照附文档依据。

逐条对照

TCP 流特性与协议横评

粘包/半包的一般处理、自定义协议的决策框架，以及 MQTT、WebSocket、RSocket、HTTP/2、HTTP/3 的机制与取舍横评。

看横评

架构与取舍

Go 参考实现的架构级讲解：整体架构、一帧的旅程、并发模型，以及每条决策的备选方案与放弃理由。

架构讲解

知识点梳理

按面试考点组织：JSON 解析文法、TCP 分帧、Go 并发与陷阱，每条先讲原理再对应到仓库实现。

复习考点

故障排查 / FAQ

Pages 大小写 404、base 与部署链、pnpm 12 构建脚本放行、fuzz/集成测试命令、codecov 门禁解读，都对到仓库实际配置。

查 FAQ

更新日志

最近十条提交的逐条摘要：每条一行，链到 GitHub commit 与相关文档页，随实质变化手工补记。

看最近改动

快速开始

bash

go get github.com/cuihairu/jsonstream

go

c, _ := jsonstream.Dial(ctx, addr, jsonstream.DefaultConfig())
m, _ := c.Request(ctx, "math.add", map[string]int{"a": 2, "b": 40}) // 请求/响应
s, _ := c.Stream(ctx, "range", map[string]int{"n": 100})           // 流式
defer s.Cancel()
sub, _ := c.Subscribe(ctx, "ticks", func(m *jsonstream.Message) error { return nil })
_ = c.Publish(ctx, "metrics", map[string]float64{"cpu": 0.42}) // client → server

压缩/加密/背压都是参数化开关，握手协商后生效（双方都开才启用）：

go

cfg := jsonstream.DefaultConfig()
cfg.Compress = true // ≥64B 载荷走 flate
cfg.Encrypt = true  // AES-256-GCM，先压后加
cfg.Key = key32     // 32 字节预共享密钥
cfg.Credit = 64     // 连接级信用窗口，生效值取双方最小

库与协议的全貌：上手与五种模式见 getting-started.md，全部公开 API 见 api.md，帧/变换/端到端的基准实测见 benchmarks.md，架构与取舍见 DESIGN.md，协议逐字段定义见 protocol.md，帧类型/Flags/错误码/配置参数的速查表在 glossary.md，与 WebSocket 的能力边界见 websocket-comparison.md，构建/测试/部署的常见问题见 faq.md，最近改动的逐条摘要在 changelog.md。