标准库网络密码学并发编程【免费下载链接】cangjie_stdx仓颉编程语言提供了 stdx 模块该模块提供了网络、安全等领域的通用能力。项目地址https://gitcode.com/Cangjie/cangjie_stdx点击查看免费下载WriteConfig是仓颉标准库扩展cangjie_stdx中stdx.encoding.json.stream包为JsonWriter提供的序列化格式配置结构体用于控制 JSON 输出的紧凑程度、缩进换行、分隔符空格、HTML 字符转义以及 DateTime 时间格式。本文以官方 API 文档为主体结合仓库源码与可验证示例系统讲解WriteConfig的两个预设格式compact、pretty与五个可变属性newline、indent、useSpaceAfterSeparators、htmlSafe、dateTimeFormat的取值约束、异常行为与底层实现原理读完即可在仓颉项目中自由定制 JSON 输出格式。WriteConfig 是什么在stdx.encoding.json.stream包中JsonWriter 负责将实现了 JsonSerializable 接口的仓颉对象序列化为 JSON 数据流而 WriteConfig 正是用来表示这种序列化格式配置的结构体。它通过JsonWriter上公开可变的writeConfig字段生效默认值为WriteConfig.compact见 json_writer.cjpublic struct WriteConfig { public static let compact: WriteConfig public static let pretty: WriteConfig }从源码看WriteConfig的私有构造函数接收五个参数分别对应五个可变属性见 json_writer.cjprivate WriteConfig( var _newline!: String, var _indent!: String, var _usesSpaceAfterSeparators!: Bool, var _htmlSafe!: Bool, var _timeFormat!: String ) {}使用时通过writer.writeConfig config将配置赋给JsonWriter即可无需重新创建 writer。下面的小节逐一拆解这些属性。两个开箱即用的预设格式WriteConfig提供了两个静态只读的预设实例覆盖了最常用的两种 JSON 输出风格。compact紧凑序列化格式compact用于生成尽可能短的 JSON 输出适合网络传输、日志落盘、存储等对体积敏感的场景。其各属性值如下属性值newline空字符串indent空字符串useSpaceAfterSeparatorsfalsehtmlSafefalsedateTimeFormatDateTimeFormat.RFC3339使用compact时JSON 输出为单行无空格形式{Name:zhangsan,Age:18,Scores:[88.8,99.9],Class:{Name:Class A,Students Number:33}}pretty整洁美化格式pretty用于生成带缩进与换行的可读性输出适合调试、配置导出、面向开发者的结果展示。其各属性值如下属性值newline\nindent包含 4 个空格的字符串useSpaceAfterSeparatorstruehtmlSafefalsedateTimeFormatDateTimeFormat.RFC3339使用pretty时同样的数据输出为多行缩进形式{ Name: zhangsan, Age: 18, Scores: [ 88.8, 99.9 ], Class: { Name: Class A, Students Number: 33 } }上述两个预设的完整取值可以在源码中直接核对compact的_newline: 、_indent: 、_usesSpaceAfterSeparators: falsepretty的_newline: \n、_indent: 、_usesSpaceAfterSeparators: true见 json_writer.cj。五个可变属性详解除预设实例外WriteConfig的五个属性均为public mut prop可以随意修改后赋给JsonWriter实现细粒度格式定制。newline换行符控制public mut prop newline: String功能表示序列化时填入的换行符取值必须匹配正则^[\r\n]*$即字符串只能包含\r、\n或为空字符串。当该值不为空字符串且合法时JsonWriter在调用startObject、startArray操作、插入元素以及对应的结束操作时都会产生换行当该值为空字符串时不会触发任何换行。异常若设置的字符串包含\r、\n以外的字符抛出IllegalArgumentException。从源码看setter 会逐个字符校验并抛错见 json_writer.cjset(v) { for (b in v where (b ! b\r b ! b\n)) { throw IllegalArgumentException(Invalid newline token: ${b}.) } _newline v }示例将pretty的换行符改为\n\n双换行后输出如下{ Name: zhangsan, Age: 18 }indent缩进字符串控制public mut prop indent: String功能序列化过程中为每个缩进级别填充的缩进字符串用于定义输出的缩进格式。取值必须匹配正则^[ \t]*$即只能包含空格、制表符或为空字符串。需要特别注意的是无换行行为时newline 为空字符串该属性不生效因为缩进只在换行后作为行首填充。异常若设置的字符串包含空格、制表符以外的字符抛出IllegalArgumentException。源码中的 setter 校验逻辑与newline类似见 json_writer.cj。示例将pretty的缩进从 4 个空格改为 1 个空格{ Name: zhangsan, Age: 18 }从底层实现看JsonWriter的newlineWithIndent方法先写换行符、再按当前嵌套层级循环写入缩进字符串见 json_writer.cj因此indent的效果与newline是否启用强相关。useSpaceAfterSeparators分隔符后空格控制public mut prop useSpaceAfterSeparators: Bool功能表示序列化时在:和,之后是否添加一个空格。该值为true时每插入一个 field name 或数组元素后会自动写入一个空格。该选项只对 JSON Object 中的字段以及 JSON Array 中的元素有效。示例在compact基础上启用该属性启用useSpaceAfterSeparators的JSON输出: {Name: zhangsan,Age: 18}可以看到:后有空格但元素间的,后没有空格——这与源码实现一致空格只在writeName写入:后通过useSpaceAfterSeparators()写入见 json_writer.cj 与 json_writer.cj而数组元素间的,后是否加空格取决于newline是否为空见 json_writer.cj。htmlSafeHTML 字符转义控制public mut prop htmlSafe: Bool功能表示是否转义 HTML 字符、、、和。该值为true时这些字符会被转义为对应的 Unicode 编码字符串如\u003c、\u003e、\u0026、\u0027。该选项只对 JSON value 中的字符串字面量有效。示例启用htmlSafe后{ Content: \u003cscript\u003ealert(\u0027XSS\u0027)\u003c/script\u003e, Title: Hello \u0026 Welcome }这一特性对需要将 JSON 嵌入 HTML 页面、防止 XSS 注入或满足严格安全审计要求的场景非常实用。dateTimeFormatDateTime 序列化格式控制public mut prop dateTimeFormat: String功能用于序列化DateTime类型时的格式控制功能与DateTime的func toString(DateTimeFormat)一致默认值为DateTimeFormat.RFC3339。属性的实际类型是String可直接赋值为任意受支持的格式串。示例将格式改为yyyy-MM-dd后DateTime.of(year: 2026, month: 1, dayOfMonth: 7)序列化为{ Name: zhangsan, DOB: 2026-01-07 }从源码看DateTime的JsonSerializable扩展正是通过writeConfig._timeFormat完成格式化的见 datetime_serialize.cjextend DateTime : JsonSerializable { public func toJson(w: JsonWriter): Unit { w.writeValue(this.format(w.writeConfig._timeFormat)) } }完整实战示例自定义并应用 WriteConfig以下示例完整演示了定义实现JsonSerializable的类 → 应用pretty配置 → 输出格式化 JSON的完整链路参考 sample_json_writeconfig.mdimport stdx.encoding.json.stream.{JsonWriter, WriteConfig, JsonSerializable} import std.io.ByteBuffer main() { /* 创建 JsonWriter */ let buffer ByteBuffer() let writer JsonWriter(buffer) /* 设置 JSON 写入格式配置 */ let fmtCfg WriteConfig.pretty writer.writeConfig fmtCfg /* 写入 JSON */ writer.writeValue(MyObj()) /* 打印 JSON 序列化字符串 */ println(String.fromUtf8(buffer.bytes())) } class MyObj : JsonSerializable { public func toJson(w: JsonWriter): Unit { w.startObject() w.writeName(Name).writeValue(zhangsan) w.writeName(Age).writeValue(18) w.writeName(Scores).writeValue([88.8, 99.9]) w.writeName(Class) w.startObject() w.writeName(Name).writeValue(Class A) w.writeName(Students Number).writeValue(33) w.endObject() w.endObject() w.flush() } }运行结果与上文pretty的输出完全一致{ Name: zhangsan, Age: 18, Scores: [ 88.8, 99.9 ], Class: { Name: Class A, Students Number: 33 } }若将fmtCfg换成WriteConfig.compact则得到单行紧凑输出{Name:zhangsan,Age:18,Scores:[88.8,99.9],Class:{Name:Class A,Students Number:33}}注意官方 API 文档明确提醒JsonWriter使用缓冲区减少对流的 I/O 操作次数结束写入前必须调用flush()确保缓冲数据全部写入流见 encoding_json_stream_package_classes.md。上面的示例也在toJson末尾调用了w.flush()。源码级原理WriteConfig 如何影响 JsonWriter 的输出要深入理解WriteConfig的每个属性可以对照JsonWriter的缓冲与状态机实现见 json_writer.cj。1. 内部缓冲与刷盘阈值JsonWriter维护一个默认容量DEFAULT_CAPACITY 4096的字节缓冲当已写位置超过FLUSH_THRESHOLD 3500时触发部分刷盘flushOutBufflush()则将剩余缓冲全部写出并调用流的flush见 json_writer.cj。这意味着WriteConfig的格式参数如多字符newline、较长的indent会直接影响缓冲消耗速度进而影响刷盘频率。2. 状态机驱动的格式写入JsonWriter内部用状态栈EmptyArray、NoEmptyArray、EmptyObject、NoEmptyObject、EmptyText、NoEmptyText跟踪嵌套结构并在状态切换时应用格式配置beforeName()在对象内写 field name 前若对象非空则先写,随后调用newlineWithIndent见 json_writer.cjbeforeValue()在数组内写元素前同样处理,与换行缩进见 json_writer.cjendArray()/endObject()在闭合括号前调用newlineWithIndent(stack.size - 2)按嵌套层级输出换行与缩进见 json_writer.cj。由此可以推断newline为空时newlineWithIndent直接返回indent随之失效useSpaceAfterSeparators则仅作用于:后的空格。三个属性在源码中的生效位置相互独立又彼此配合构成了完整的美化输出机制。3. 非法配置的防御newline与indent的 setter 都在赋值时进行逐字符合法性校验一旦出现非法字符立即抛出IllegalArgumentException避免脏数据进入序列化流程。与 JsonWriter、JsonSerializable 的协作关系WriteConfig并非独立使用而是深度嵌入JsonWriter的序列化链路JsonWriterpublic var writeConfig: WriteConfig WriteConfig.compact默认即紧凑格式用户可在构造后随时替换见 encoding_json_stream_package_classes.mdJsonSerializable用户类实现toJson(w: JsonWriter)接口方法通过w.writeName(...).writeValue(...)等链式调用描述结构格式细节完全交由writeConfig处理见 encoding_json_stream_package_interfaces.md内建类型扩展Int64、UInt64、Float64、Bool、String以及集合类型Array、ArrayList、HashMap、DateTime等均已内建JsonSerializable实现可直接作为writeValue的参数WriteConfig的格式规则对它们统一生效。小结与选型建议WriteConfig是cangjie_stdx中控制JsonWriter输出格式的唯一入口设计上做到了结构描述与格式控制分离业务代码只负责描述 JSON 结构格式由配置驱动。选型时可参考以下建议网络传输、存储、体积敏感直接用WriteConfig.compact或保持默认调试、日志、配置导出使用WriteConfig.pretty可按需微调indent如改为 2 空格或newlineJSON 嵌入 HTML 或安全审计在pretty/compact基础上开启htmlSafe true自定义时间格式修改dateTimeFormat为需要的格式串如yyyy-MM-dd、yyyy-MM-dd HH:mm:ss。更多上下文可参阅stdx.encoding.json.stream包总览 json_stream_package_overview.md、JsonWriter/JsonReader类文档 encoding_json_stream_package_classes.md 及源码实现 json_writer.cj中文版 API 文档还提供了每个属性的独立可运行示例见 encoding_json_stream_package_structs.md。赞分享标准库网络密码学并发编程【免费下载链接】cangjie_stdx仓颉编程语言提供了 stdx 模块该模块提供了网络、安全等领域的通用能力。项目地址https://gitcode.com/Cangjie/cangjie_stdx点击查看免费下载相关推荐仓颉 JSON 流序列化格式配置WriteConfig 使用指南JsonWriter 之 pretty/compact 实战仓颉 JSON 流序列化格式配置WriteConfig 使用指南JsonWriter 之 pretty/compact 实战 本篇基于仓颉编程语言 std文档知识库教程OpenHarmonycangjie_stdx json.stream 包实战指南JsonReader 与 JsonWriter 的流式 JSON 序列化/反序列化全解析cangjie_stdx json.stream 包实战指南JsonReader 与 JsonWriter 的流式 JSON 序列化/反序列化全解析 stdx标准库网络密码学并发编程RocketRide RAG 管道实战从 Webhook 到 Qdrant 的检索增强生成完整实现RocketRide RAG 管道实战从 Webhook 到 Qdrant 的检索增强生成完整实现 检索增强生成RAG是 RocketRide 中最常见的文档知识库教程OpenHarmony创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考