★ FEATURED ARTICLE 文档编程语言【免费下载链接】cangjie_docs仓颉编程语言开发者文档。项目地址https://gitcode.com/Cangjie/cangjie_docs点击查看免费下载本文以仓颉Cangjie中心仓文档中的元数据规格附录为主体完整解析meta-data.json元数据规格与制品包索引index规格的全部字段及其语义并结合cjpm bundle、cjpm publish的打包发布流程与中心仓通信协议说明这些字段如何被仓库端用于入库检查、网页端制品展示和cjpm依赖解析。读完本文你将能够读懂一份真实的元数据文件、理解索引条目中依赖项的平台/编译模式隔离机制以及在发布制品时保证校验码与元数据一致性。一、元数据从哪来cjpm bundle打包流程cjpm bundle命令会将本地开发的源码模块打包成符合中心仓制品包格式的制品源码包并同时生成该模块的元数据。根据 制品包发布 一节bundle的打包流程分为四步模块检查模块名、组织名满足规格要求长度 [3, 64]、非仓颉关键字、组织名不能为defaultcjpm.toml中必须包含description根目录需包含README.md或README_zh.md模块的依赖项均为中心仓形式。不满足则打包失败编译检查确保模块能编译通过未配置--skip-test时还会运行单元测试编译或测试失败均导致打包失败代码静态检查未配置--skip-lint时调用cjlint进行静态检查出现error级别错误则打包失败打包基于include和exclude字段将模块打包成tar.gz格式的制品源码包文件名为模块名-版本号.cjp同时生成制品包对应的元数据文件meta-data.json两者都位于编译产物目录中。例如待打包模块demo的版本号为1.0.0、未自定义编译产物目录默认为target执行cjpm bundle后目录内容如下引自 制品包发布target ├── demo-1.0.0.cjp # 制品源码包 ├── meta-data.json # 制品元数据 └── 其他编译产物demo-1.0.0.cjp可按tar.gz格式解压。bundle命令还提供-V, --verbose、--skip-test、--skip-lint三个可配置项见 cjpm 使用手册 的 bundle 小节。后续执行cjpm publish时cjpm会检查编译产物目录中是否存在模块名-版本号.cjp和meta-data.json若任一文件缺失或元数据中记录的制品包校验码sha256sum与实际制品包不匹配则重新执行默认bundle流程随后才把有效的制品源码包和元数据发布到中心仓。这正是元数据中sha256sum字段在客户端侧的核心用途。二、元数据规格meta-data.json字段全解元数据记录了待打包模块的关键信息用于仓库端入库检查和网页端制品展示。元数据规格如下引自 中心仓元数据规格{ organization: cangjie, // 组织名为空则为无组织 name: demo, // 模块名 version: 1.0.0, // 版本号 cjc-version: 1.0.0, // 仓颉 SDK 版本号 description: demo for cangjie central repository, // 模块描述 artifact-type: src, // 制品包类型固定为源码包 src executable: true, // 是否可以编译成可执行程序cjpm.toml 中 package.output-type executable 时该值为 true否则为 false authors: [Tom, Joan], // 作者 ID 列表 repository: https://github.com/xxx, // 制品代码仓 homepage: https://xxx.com, // 制品主页 documentation: https://xxx.com/docs, // 制品文档页 tag: [cangjie, cjpm], // 制品标签 category: [Network], // 制品分类 license: [Apache-2.0], // 协议列表 index: { ... }, // 制品包索引 meta-version: 1 // 元数据规格版本号 }2.1 字段逐一说明字段类型语义与来源organizationstring组织名为空表示该制品包不隶属于任何组织namestring模块名与cjpm.toml中name一致且须与模块内root包名一致versionstring制品版本号格式为主版本号.次版本号.修订版本号三级均为自然数如0.1.2、123.456.789cjc-versionstring仓颉 SDK 最低版本号即编译该制品所需的最低 SDK 版本descriptionstring模块描述打包时必填在网页端展示artifact-typestring制品包类型固定为源码包srcexecutablebool是否能编译成可执行程序cjpm.toml中package.output-type executable时为true否则为false。中心仓官网制品页据此展示该制品包是否可用cjpm install安装见 制品包使用authorsstring[]作者 ID 列表用于在中心仓页面展示repositorystring制品代码仓 url可选用于中心仓页面展示homepagestring制品主页 url可选用于中心仓页面展示documentationstring制品文档页 url可选用于中心仓页面展示tagstring[]制品标签上限 5 个见 cjpm 使用手册 的 tag 字段说明categorystring[]制品分类上限 5 个取值必须为中心仓提供的标准分类配置时大小写不敏感但生成的元数据中会被转化为标准格式licensestring[]协议列表取值需遵循 SPDX Identifier 规范indexobject制品包索引记录依赖信息见下文第三节meta-versionint元数据规格版本号当前为1tag、repository、homepage、documentation、license等字段均直接来源于cjpm.toml中的同名配置项。制品名和组织名的命名规格大小写字母、数字、下划线长度 [3, 64]不能是仓颉关键字组织名不能为default详见 中心仓制品规格。2.2category的合法取值元数据中category的取值必须落在中心仓提供的分类范围内。根据 cjpm 使用手册完整的制品分类列表如下分类名category网络Network数据库驱动Database Driver数据封装传递Data Encapsulation and Transfer数据解析Data Analysis数据库框架Database Framework对象存储Object Storage分布式Distributed任务调度Task Scheduling安全类Security工具类Utility日志类Logging算法类Algorithm音视频Audio and Video字符编码Character Encoding图像处理Image Processing开发者工具Developer Tools动画类Animation基础设施Infrastructure地理信息Geographic InformationUI 类UI科学计算Scientific Computing编程框架Programming Framework数据监控Data Monitoring熔断降级Circuit Breaker and Downgrading消息队列Message Queue2.3 与cjpm.toml配置的对应关系元数据字段与cjpm.toml中相关配置的对应关系如下字段清单引自 制品包发布cjpm.toml字段说明是否必填对应元数据字段cjc-version仓颉 SDK 最低版本号是cjc-versionname模块名与模块内root包名一致是nameorganization组织名为空则为无组织模块否organizationdescription描述信息仅打包时必填descriptionversion模块版本信息是versionoutput-type编译输出产物类型static/dynamic/executable是executableauthors作者 ID 列表否authorsrepository制品代码仓 url否repositoryhomepage制品主页 url否homepagedocumentation制品文档页 url否documentationtag制品标签否tagcategory官方提供的制品分类否categorylicense协议列表否licensedependencies等项目依赖、测试依赖、脚本依赖否index中对应依赖数组一个完整的cjpm.toml示例[package] cjc-version 1.0.0 name demo organization cangjie description demo of cangjie central repository version 1.0.0 output-type executable authors [Tom, Joan] repository https://cangjie-demo.git homepage https://cangjie-demo.com documentation https://cangjie-demo.com/docs tag [cangjie, demo] category [Network, UI] license [Apache-2.0] include [src] exclude [*.txt] [dependencies] aoo 1.0.0 [test-dependencies] boo 2.0.0 [script-dependencies] org::coo 3.0.0其中include与exclude影响的是demo-1.0.0.cjp内包含哪些文件gitignore 风格 glob 语法不直接进入元数据但决定制品包的内容范围从而间接影响sha256sum。三、制品包索引规格依赖信息如何被cjpm使用元数据中的index字段是制品包索引记录制品包的依赖信息cjpm可利用索引进行依赖解析而无需下载制品源码。索引规格如下引自 中心仓元数据规格{ organization: cangjie, // 组织名为空则为无组织 name: demo, // 模块名 version: 1.0.0, // 版本号 cjc-version: 1.0.0, // 仓颉 SDK 版本号 dependencies: [{ // 源码依赖项 name: dep1, // 依赖项模块名 require: 1.1.0, // 依赖项版本需求 target: null, // 平台隔离标识target null 表示该依赖项不区分平台 type: null, // 编译模式标识type null 表示该依赖项不区分编译模式 output-type: null // 编译产物类型表示output-type null 表示该依赖项的编译产物遵循对应源码模块内 package.output-type 的取值 }, { name: org::dep2, // 组织内依赖项模块名 require: [1.0.0, 2.0.0), // 依赖项版本需求 target: x86_64-unknown-linux-gnu, // 平台隔离标识target 有取值表示该依赖项仅适用于对应平台 type: debug, // 编译模式标识type debug/release 表示该依赖项仅适用于 debug(-g) / 非 debug 编译模式 output-type: static // 编译产物类型表示output-type static/dynamic 表示该依赖项对应模块将被编译为静态库 / 动态库 }], test-dependencies: [], // 测试依赖项与源码依赖项格式一致 script-dependencies: [], // 构建脚本依赖项与源码依赖项格式一致 sha256sum: ..., // 对应制品包的 SHA-256 校验码用于验证制品包完整性 yanked: false, // 制品包弃用表示yanked true 表示该制品包已被弃用 index-version: 1 // 索引规格版本号 }3.1 依赖项的五个字段每个依赖项dependencies、test-dependencies、script-dependencies三类格式一致包含字段语义name依赖项模块名组织内依赖项以组织名::模块名形式表示如org::dep2require依赖项版本需求支持单一版本号、版本范围数学区间可自定义开闭、上下界可缺省及多区间组合格式与 制品包使用 中描述的cjpm.toml依赖写法一致。例如1.1.0表示精确依赖1.1.0[1.0.0, 2.0.0)表示大于等于1.0.0且小于2.0.0的任意版本(, 2.0.0]、(1.0.0, )、(, )分别表示任意小于等于2.0.0、任意大于1.0.0、任意版本target平台隔离标识null表示该依赖项不区分平台有取值如x86_64-unknown-linux-gnu则表示仅适用于对应平台。平台名可在对应平台上通过cjc -v获取type编译模式标识null表示不区分编译模式debug/release分别表示仅适用于 debug-g/ 非 debug 编译模式output-type编译产物类型null表示遵循被依赖模块自身package.output-type的取值static/dynamic表示该模块将被编译为静态库/动态库这套target/type隔离机制与cjpm.toml中[target.平台.debug|release.dependencies]的平台隔离依赖配置一一对应本地模块按平台隔离声明的依赖打包后即固化到索引的target、type字段中。这也解释了为何同一个制品包在不同平台、不同编译模式下可以解析出不同的依赖版本。版本大小关系按主版本号、次版本号、修订版本号优先级依次比较例如1.2.3 1.4.5、3.4.5 2.40.50。3.2 三类依赖的用途索引中的三类依赖数组对应cjpm的三种依赖场景引自 制品包使用dependencies源码依赖为项目源码提供依赖模块test-dependencies测试依赖仅在为_test.cj结尾的测试代码编译/测试时生效script-dependencies脚本依赖仅对与cjpm.toml同级的构建脚本build.cj生效。三者相互隔离构建脚本只能使用script-dependencies项目源码和测试代码不能使用脚本依赖但项目源码依赖dependencies也可被测试代码使用。3.3sha256sum、yanked与规格版本sha256sum对应制品包.cjp的 SHA-256 校验码用于验证制品包完整性。它在两处发挥作用一是publish前cjpm用它校验本地制品包是否与元数据匹配不匹配则重新bundle二是仓库端对下载内容的完整性保障。yanked制品包弃用标识yanked true表示该制品包已被弃用。依赖解析时被弃用的版本不再作为可用版本参与解析从而让依赖方平滑迁移到新版本。index-version索引规格版本号当前为1。它与元数据的meta-version分开编号意味着两者可独立演进。四、元数据与索引在中心仓通信中的角色了解字段之后再看这些字节流如何真正在客户端与中心仓之间流动。根据 中心仓通信规格以用户在cangjie-repo.toml中配置的repository.home.registry为基础4.1 制品包上传meta-version与index-version的字节级使用cjpm publish发送POST请求url为无组织模块的/pkg/${module-name}或组织内模块的/pkg/${module-name}?organization${org-name}url 中不体现版本号header携带Authorization${token}。body由两段变长结构拼接元数据段元数据版本1 byte对应元数据内的meta-version 元数据长度4 byte即元数据字节长度 m 元数据内容m byte整个元数据字节流制品包段制品包版本1 byte对应索引内的index-version 制品包长度4 byte即制品包字节长度 n 制品包内容n byte整个制品包字节流。也就是说元数据中看似“元信息”的meta-version、index-version两个字段在通信层直接决定了服务端如何切分、解析后续字节流——这正是规格版本号字段的实际工程意义。例如上传无组织模块demo1的1.0.0版本时url /pkg/demo1上传组织org的模块demo2的2.0.0版本时url /pkg/demo2?organizationorg。4.2 索引下载依赖解析的轻量通道制品包索引支持独立下载cjpm在依赖解析过程中或在update命令中会向中心仓发送索引下载请求方法GETurl无组织制品为/index/${mo}/${du}/${module-name}组织内制品为/index/${mo}/${du}/${module-name}?organization${org-name}返回数据制品索引文件其中每行均为一个json索引条目。mo、du是制品名前两、三个字符的拆分用于将索引分片存放。例如下载无组织制品aabbcc的索引时url /index/aa/bb/aabbcc下载组织org的制品dep的索引时url /index/de/p/dep?organizationorg。按行组织的格式意味着同一制品的所有版本索引条目都存放在一个文件中cjpm可一次拉取后在本地进行版本需求匹配——这正是“利用索引进行依赖解析”而不必逐个下载源码包的原理。依赖解析成功后cjpm再按最终确定的每个制品版本发送制品包下载请求GET /pkg/${module-name}/version返回tar.gz格式的源码压缩包并缓存到cangjie-repo.toml配置的本地缓存路径下默认~/.cjpm见 中心仓客户端配置。4.3 与元数据相关的返回码通信规格定义了统一的返回码语义引自 中心仓通信规格返回码含义200成功400参数错误可能是元数据或索引解析错误401用户认证失败403用户无权限或制品包名已被占用制品包名不区分大小写404文件不存在409上传的制品包与仓库已有制品包冲突429每日请求频率超限500服务器故障其中400直接对应元数据/索引的解析失败场景——当meta-version或index-version与服务端支持的规格版本不一致、或 JSON 结构不合法时仓库端会以此返回码拒绝请求。403与409则对应publish成功条件中“制品包唯一”和“组织成员权限”两类检查制品包唯一性要求仓库中不存在另一个与新上传制品包的组织名、制品名、版本号均相同的制品包若制品包隶属某组织token 对应用户须是该组织成员发布还需通过中心仓的安全扫描。五、实践要点小结元数据不是手工编写的meta-data.json由cjpm bundle从cjpm.toml自动生成并计算sha256sum开发者应通过修改cjpm.toml来调整制品信息而不是直接编辑元数据文件。executable决定安装能力只有package.output-type executable的制品包其元数据中executable为true才能通过cjpm install [org::]name-version安装为可执行程序其他产物类型static/dynamic的制品包只能作为依赖项引入。依赖解析优先走索引cjpm依赖解析依赖的是索引条目含dependencies/test-dependencies/script-dependencies、yanked制品包本体只在解析成功后下载cjpm update可刷新本地索引缓存以获取中心仓最新的制品信息。校验码一致性是publish的前置条件改动源码后若未重新bundle旧的meta-data.json中sha256sum会与实际.cjp不匹配publish会自动触发重新bundle以保证发布内容的一致性。规格版本字段面向演进meta-version与index-version目前均为1它们在上传协议中以单字节版本头参与字节流切分为后续规格升级预留了兼容判断依据。更多相关文档可参考中心仓制品规格、中心仓通信规格、制品包使用、中心仓客户端配置 与 cjpm 使用手册。赞分享文档编程语言【免费下载链接】cangjie_docs仓颉编程语言开发者文档。项目地址https://gitcode.com/Cangjie/cangjie_docs点击查看免费下载相关推荐仓颉中心仓通信规格详解cjpm 如何与中心仓交互上传/下载制品与索引仓颉中心仓通信规格详解cjpm 如何与中心仓交互上传/下载制品与索引 本文围绕仓颉中心仓Cangjie Central Repository的通信规格展开文档编程语言仓颉中心仓制品包发布指南cjpm bundle 与 publish 全解析仓颉中心仓制品包发布指南cjpm bundle 与 publish 全解析 本文基于仓颉开发者文档仓库cangjie_docs中的中心仓客户端文档系统讲文档编程语言仓颉中心仓通信规格详解cjpm 制品包上传、下载与索引接口的完整设计仓颉中心仓通信规格详解cjpm 制品包上传、下载与索引接口的完整设计 仓颉中心仓Cangjie Central Repository是仓颉语言的三方库托管文档编程语言创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
