Skip to main content

消息体规范

本文档定义了 KnotLink 协议中消息体的推荐数据表达格式，旨在为开发者提供一套统一、灵活、可互转的数据表达方案。遵循本规范有助于提升生态内软件间的互操作性，降低接入与维护成本。

一、格式概览​

KnotLink KLUDF库支持三种标准化的数据表达格式，可根据场景灵活选用：

格式设计目标适用场景示例
键值对（Key-Value）轻量、简洁、低解析开销简单参数传递、IoT/嵌入式设备通信name=张三;age=18
JSON结构化、可嵌套、机器友好复杂数据交换、程序间通信、配置存储{"name":"张三","age":18}
（CLI）命令行参数格式人类易输入、命令式交互CLI 交互、Shell 脚本调用--name 张三 --age 18

二、键值对格式​

键值对（Key-Value Pairs）

键值对：最简单的数据交换格式之一，仅由键和值组成，通常以简单的分隔符（如冒号或等号）分隔。示例：

key1=value1;key2=value2

基本信息​

属性说明
名称键值对（Key-Value Pairs）
设计目标轻量、简洁、低解析开销
适用场景简单参数传递

格式规范​

键值对格式由多个键值对组成，键和值之间用 = 分隔，不同的键值对之间用 ; 分隔。

规则说明​

规则说明示例
键值分隔符键和值之间使用 =name=张三
对分隔符多个键值对之间使用 ;name=张三;age=18
键命名建议仅包含字母、数字、下划线user_name、course_id
值类型所有值均视为字符串age=18 视为字符串 "18"
空白字符建议建议不包含空格name=张三 而非 name = 张三
注意

使用键值对格式时，请保证您的键与值中不包括"="及";"

示例​

# 基本用法
course=数学;room=A201;teacher=张老师

# 包含下划线的键
user_name=张三;course_id=MATH101

# 多值场景（以字符串表示）
students=张三,李四,王五;course=数学

三、JSON 格式​

JSON（JavaScript Object Notation）

JSON：一种轻量级的数据交换格式，易于人阅读和编写，同时也易于机器解析和生成。它支持复杂的数据结构，如嵌套的对象和数组。JSON由键值对组成，键和值之间用冒号分隔，不同的键值对之间用逗号分隔，并且整个结构由大括号包围。示例：

{
  "key1": "value1",
  "key2": "value2",
  "key3": ["item1", "item2", "item3"],
  "key4": {
    "subKey1": "subValue1",
    "subKey2": "subValue2"
  }
}

基本信息​

属性说明
名称JSON（JavaScript Object Notation）
设计目标结构化、可嵌套、机器友好
适用场景复杂数据交换、程序间通信、配置存储

格式规范​

JSON 格式遵循 RFC 8259 标准。数据由键值对组成，键和值之间用冒号 : 分隔，不同的键值对之间用逗号 , 分隔，整个结构由大括号 {} 包围。

数据类型​

类型说明示例
字符串双引号包裹"hello"
数字整数或浮点数123、3.14
布尔值true 或 falsetrue
数组有序列表[1, 2, 3]
对象嵌套的键值对{"key": "value"}
空值nullnull

示例​

{
  "course": "数学",
  "room": "A201",
  "teacher": "张老师",
  "students": ["张三", "李四", "王五"],
  "schedule": {
    "start": "10:00",
    "end": "10:45"
  }
}

四、命令行格式（暂未实现）​

基本信息​

属性说明
名称命令行参数格式，遵循 GNU 风格命令行选项标准
设计目标人类易输入、命令式交互
适用场景CLI 交互、Shell 脚本调用

格式规范​

命令行格式以命令行参数形式表达数据，键以 -- 或 - 为前缀，键与值之间用空格或等号 = 分隔，多个参数之间用空格分隔。

--key1 value1 --key2 value2
--key1=value1 --key2=value2
-k1 value1 -k2 value2

规则说明​

规则说明示例
长选项以 -- 开头--course
短选项以 - 开头（单字符）-c
键值分隔空格或 =--course 数学 或 --course=数学
多参数用空格分隔--course 数学 --room A201
带空格的参数值用引号包裹--message "今天天气真好"
复杂参数使用 JSON 字符串--params '{"course":"数学","time":"10:00"}'

示例​

# 基本用法
--course 数学 --room A201 --teacher 张老师

# 使用等号连接
--course=数学 --room=A201

# 包含空格的参数值
--message "今天天气真好"

# 短选项形式（简写）
-c 数学 -r A201

# 复杂参数（JSON 字符串）
--params '{"course":"数学","time":"10:00"}'

五、版本历史​

版本日期变更说明
v1.02026-06-21初始版本，纳入键值对、JSON、CLI 三种格式。

本文档是 KnotLink 协议规范的一部分，遵循 KnotLink 开源许可证。