后端并发编程分布式【免费下载链接】cactor项目地址https://gitcode.com/Cangjie-SIG/cactor点击查看免费下载本文基于 CActor 仓库的代码风格指南docs/CODE_STYLE_GUIDE.md系统讲解该项目面向仓颉Cangjie语言制定的全套编码规范命名约定、注释与文档规范、文件与类内部结构、格式化规则、错误处理模式、性能编码准则以及测试与审查流程。读完本文你可以在为 CActor 这类 Actor 系统贡献代码或阅读其源码时准确判断一段 Cangjie 代码是否符合项目惯例并理解每条规范背后的设计动机与在仓库中的实际落地方式。规范定位为什么 Actor 框架需要严格的代码风格CActor 是一个基于仓颉语言构建的高性能 Actor 系统仓库根部的 cjpm.toml 声明其当前版本为 7.0.0采用 6 层架构foundation / core / runtime / api / patterns / xstate依赖cjc-version 0.60.5编译器。项目由数十个 Cangjie 包构成每个包对应 src 下的一个目录并以pkg.cj声明包信息模块之间通过import互相引用。在这种多包、多层、多线程并发处理的代码库中统一风格的价值在于跨层可读性从 foundation 的队列/内存池到 runtime 的邮箱/调度器命名一致可以让读者快速定位符号语义并发安全可审查Actor 系统大量涉及无锁队列、状态标志位等并发结构规范的类内部结构与注释要求让线程安全问题在代码审查中更容易被发现工具化落地编译选项如compile-option -Woff unused ...与静态分析命令配合风格规则可以部分自动化检查。以下各节完整覆盖指南的每一条规则并结合仓库源码给出佐证。命名约定六种元素的命名标准指南将命名约定拆分为类名、接口名、函数名、变量名、常量名、包名六类每类均给出了正确与错误示例。类名与接口名PascalCase// ✅ 正确 class ActorSystem class MessageProcessor class ErrorHandlingManager interface Actor interface MessageHandler interface ErrorHandlingStrategy // ❌ 错误 class actorSystem interface messageHandler interface error_handling_strategy仓库源码完全符合这一约定。src/core/actor/actor.cj 中的Actor接口定义了receive、preStart、postStart、preStop、postStop、preRestart、postRestart等生命周期方法同文件的ActorLifecycleState枚举以| Created | Starting | Running | ...列出七种状态。src/core/error/error_handling.cj 中的CActorException、CActorErrorCode、ErrorSeverity也都是标准 PascalCase。函数名camelCase// ✅ 正确 func processMessage() func handleError() func createActorSystem() // ❌ 错误 func ProcessMessage() func handle_error() func CreateActorSystem()注意规则同时排除了 Java 风格的 PascalCase 函数名ProcessMessage与 C 风格的 snake_casehandle_error。源码中Actor接口的func receive(message: Message, context: ActorContext): MessageResultsrc/core/actor/actor.cj、error_handling.cj中的func getErrorCode()/func getSeverity()均遵循该规则。变量名camelCase// ✅ 正确 let messageCount: Int64 let processingTime: Duration let errorHandlingStrategy: ErrorHandlingStrategy // ❌ 错误 let MessageCount: Int64 let processing_time: Duration佐证src/tests/unit/core/actor/simple_actor_test.cj 中private var messageCount: Int32 0、private var lastMessage: String 是典型的双词 camelCase 成员变量。常量名SCREAMING_SNAKE_CASE// ✅ 正确 let MAX_MESSAGE_SIZE: Int64 1024 let DEFAULT_TIMEOUT: Duration Duration.second * 30 let ACTOR_SYSTEM_NAME: String CActor // ❌ 错误 let maxMessageSize: Int64 1024这一点在 CActor 的并发基础组件中体现得尤为明显——无锁队列与状态标志位全部使用大写常量// src/foundation/queue/lockfree_queue.cj public static let EMPTY: Int64 0 public static let FILLED: Int64 1 public static let WRITING: Int64 2 public static let READING: Int64 3 // src/runtime/actor/high_performance_actor.cj public static let RUNNING_FLAG: UInt32 0x01 public static let SUSPENDED_FLAG: UInt32 0x02 public static let STOPPED_FLAG: UInt32 0x04 public static let FAILED_FLAG: UInt32 0x08 public static let RESTARTING_FLAG: UInt32 0x10 public static let HIGH_PRIORITY_FLAG: UInt32 0x20可见 src/foundation/queue/lockfree_queue.cj、src/runtime/actor/high_performance_actor.cj 以及 src/runtime/mailbox/lockfree/lockfree_mailbox.cj 中状态机标志位与位掩码常量统一采用SCREAMING_SNAKE_CASE使并发语义在代码中一目了然。包名snake_case// ✅ 正确 package cactor.core.actor package cactor.runtime.dispatcher package cactor.patterns.ask // ❌ 错误 package cactor.Core.Actor该规则与仓库的实际包结构一一对应cjpm.toml 中package-configuration逐包声明了cactor.foundation.memory、cactor.foundation.queue、cactor.core.actor、cactor.runtime.mailbox、cactor.patterns.ask、cactor.xstate.core等包名全部小写点分层级层级顺序固定为“顶层cactor→ 层名foundation/core/runtime/api/patterns/xstate→ 子模块”。同时可以观察到各层包的产物类型约定foundation/core/api/patterns 层为staticruntime/macros 层为dynamic示例与集成测试包为executable这套约定也属于项目整体命名与组织规范的一部分。注释规范文档注释、行内注释与 TODO 体系类注释指南要求的类注释模板包含功能描述、设计背景与版本/作者元信息/** * Actor系统的核心实现 * * 负责管理Actor的生命周期、消息路由和系统配置。 * 参考Akka设计模式为仓颉语言量身定制。 * * since 1.0.0 * author CActor Team */ class CActorSystemImpl : ActorSystem { // 实现细节 }函数注释函数注释必须覆盖param、return、throws三类信息/** * 处理接收到的消息 * * param message 要处理的消息不能为null * param context Actor上下文包含发送者信息 * return 消息处理结果表示是否成功处理 * throws CActorException 当消息处理失败时抛出 */ func receive(message: Message, context: ActorContext): MessageResult { // 实现逻辑 }这一模板在 src/core/actor/actor.cj 中有真实落地Actor接口的receive方法注释正是“说明 param× 2 return”的标准形式/** * 处理接收到的消息 * param message 接收到的消息 * param context Actor上下文 * return 消息处理结果 */ func receive(message: Message, context: ActorContext): MessageResult行内注释与标记约定// 计算平均处理时间毫秒 let avgProcessingTime totalTime / messageCount // TODO: 实现更高效的消息路由算法 // FIXME: 修复并发访问时的竞态条件 // NOTE: 这里使用简化实现生产环境需要优化指南明确区分了TODO待实现、FIXME已知缺陷、NOTE实现取舍说明三种标记。在并发组件中NOTE类说明尤其重要——例如 src/foundation/queue/lockfree_queue.cj 这类无锁结构行内注释需要说明内存序或状态机转移的意图。文件头版权注释块结合下一条“文件组织”规则CActor 的每个源文件以统一的块注释开头。以 src/core/error/error_handling.cj 为例/* * Copyright (c) 2024. All rights reserved. * CActor 统一错误处理模块 * Plan 0.20 Phase 2.2: 错误处理标准化 - 统一错误处理实现 */ package cactor.core.error从源码结构看第三行还承载了项目规划信息Plan 编号 阶段 主题相当于把“这个文件为什么存在”直接写进了文件头这是 CActor 在通用版权头之上的自有扩展。代码结构文件组织与类内部布局文件组织顺序指南规定了源文件内元素的出现顺序版权头 →package声明 → 分组的import标准库 → CActor 核心模块 → 第三方库→ 类型定义 → 接口定义 → 类实现/* * Copyright (c) 2024. All rights reserved. * CActor - 文件功能描述 * 详细说明文件的作用和设计思路 */ package cactor.core.actor // 1. 标准库导入 import std.time.* import std.collection.* // 2. CActor核心模块导入 import cactor.core.message.* import cactor.core.context.* // 3. 第三方库导入如果有 // 4. 类型定义 public enum MessageResult { // 枚举值 } // 5. 接口定义 public interface Actor { // 接口方法 } // 6. 类实现 public class ActorImpl : Actor { // 类实现 }src/core/actor/actor.cj 是这一顺序的精确实例版权头 →package cactor.core.actor→import std.time.*→import cactor.core.message.*/import cactor.core.context.*→ 枚举ActorLifecycleState→ 接口Actor→ 类实现。类内部结构类内部的成员按固定顺序排列共六段class ExampleActor : Actor { // 1. 常量定义 private static let MAX_RETRIES: Int32 3 // 2. 属性定义 private var messageCount: Int64 0 private let startTime: Int64 // 3. 构造函数 public init() { this.startTime System.currentTimeMillis() } // 4. 公共属性 public prop name: String { get() { ExampleActor } } // 5. 公共方法 public func receive(message: Message, context: ActorContext): MessageResult { // 实现 } // 6. 私有方法 private func processMessage(message: Message): Unit { // 实现 } }测试代码中的SimpleTestActor展示了同一布局的真实形态src/tests/unit/core/actor/simple_actor_test.cjprivate var messageCount/private var lastMessage属性在前public prop name/public prop description公共只读属性居中receive公共方法与getMessageCount、reset查询/重置方法在后。属性使用 Cangjie 的propget()语法暴露只读视图而不是生成额外的 getter 方法这是与 Java 风格的关键差异。格式化规范缩进、行宽与空行缩进与空格统一使用 4 个空格缩进禁止 Tab 或混用// ✅ 正确 - 使用4个空格缩进 class Actor { func receive(message: Message): MessageResult { match (message) { case ping: PingMessage MessageResult.Handled case _ MessageResult.Unhandled } } }Cangjie 的match表达式是消息分发的惯用法case ... ...分支体与case对齐缩进两级src/tests/unit/core/actor/simple_actor_test.cj 中receive方法的match (message) { case msg: StringMessage ... case _ ... }即为标准写法。行长度单行不超过 120 字符超长参数列表应在参数之间换行每个参数独占一行// ✅ 正确 - 长行适当换行 let result processMessage( message, context, additionalParam, anotherParam )空行使用成员定义之间、逻辑块之间用空行分隔match的各个case分支之间以空行隔开class ExampleActor : Actor { private var count: Int64 0 public func receive(message: Message, context: ActorContext): MessageResult { count 1 match (message) { case ping: PingMessage handlePing(ping) MessageResult.Handled case pong: PongMessage handlePong(pong) MessageResult.Handled case _ MessageResult.Unhandled } } private func handlePing(ping: PingMessage): Unit { // 处理ping消息 } private func handlePong(pong: PongMessage): Unit { // 处理pong消息 } }这个“case 之间空行”的排版习惯同样出现在 src/core/actor/actor.cj 的ActorLifecycleState.toInt64()/fromInt64()等 match 块中。错误处理规范具体异常捕获与 Result/Option 返回异常处理必须捕获具体异常类型并按类型分支处理禁止空捕获// ✅ 正确 - 具体的异常处理 try { processMessage(message) } catch (e: CActorException) { // 处理CActor特定异常 handleCActorError(e) } catch (e: Exception) { // 处理通用异常 handleGenericError(e) } // ❌ 错误 - 捕获所有异常但不处理 try { processMessage(message) } catch (e: Exception) { // 空的异常处理 }这条规则与 CActor 的统一错误处理模块直接对应。src/core/error/error_handling.cj 定义了三层结构错误码枚举CActorErrorCode按位段划分错误域——系统级1000-1999、Actor 级2000-2999如ActorNotFoundError、ActorMailboxFullError、消息级3000-3999如MessageTimeoutError、网络级4000-4999、持久化5000-5999、集群6000-6999、通用9000-9999严重级别枚举ErrorSeverityCritical/High/Medium/Low/Info统一异常类CActorException : Exception携带errorCode、severity、timestamp与HashMapString, String形式的上下文并提供带 severity 与不带 severity默认Medium两个init重载。因此指南中catch (e: CActorException)的写法不是抽象示例而是指向该模块定义的真实类型。错误返回Result 与 Option指南推荐两种函数式返回模式// ✅ 正确 - 使用Result类型 func processMessage(message: Message): ResultUnit, CActorError { if (message.isValid()) { // 处理消息 Ok(()) } else { Err(CActorError.InvalidMessage(消息格式无效)) } } // ✅ 正确 - 使用Option类型 func findActor(name: String): OptionActorRef { if (actors.containsKey(name)) { Some(actors[name]) } else { None } }仓库中Option的使用有直接佐证测试框架的 src/integration/testing/test_framework.cj 中TestExpectation枚举的getValue()方法成功时返回Some(value)、失败返回None正是“用 Option 表达可能缺失的查询结果”这一规范的落地。性能规范对象重用与集合选型避免不必要的对象创建热点路径上的格式化操作应重用缓冲对象// ✅ 正确 - 重用对象 class MessageProcessor { private let stringBuilder: StringBuilder StringBuilder() func formatMessage(message: Message): String { stringBuilder.clear() stringBuilder.append(Message: ) stringBuilder.append(message.toString()) stringBuilder.toString() } } // ❌ 错误 - 频繁创建对象 func formatMessage(message: Message): String { let sb StringBuilder() // 每次都创建新对象 sb.append(Message: ) sb.append(message.toString()) sb.toString() }这一原则与 CActor 的 runtime 层设计目标一致——消息处理是每消息必走的热路径src/runtime 下存在 batching mailbox、对象池src/foundation/memory/object_pool.cj等配套机制来减少分配。高效的集合操作// ✅ 正确 - 预分配容量 let messages ArrayListMessage(expectedSize) // ✅ 正确 - 使用合适的集合类型 let actorIndex HashMapString, ActorRef() // 快速查找 let messageQueue ArrayDequeMessage() // 高效队列操作 // ❌ 错误 - 使用不合适的集合类型 let actorIndex ArrayListPairString, ActorRef() // 查找效率低选型要点可以概括为键值查找用HashMap如 Actor 注册表按名称查找ActorRef、FIFO 场景用ArrayDeque消息队列、邮箱底层、已知规模时通过构造函数预分配容量避免扩容。测试规范命名约定与 AAA 结构测试命名测试方法名必须描述“条件 预期行为”禁止test1这类无信息量命名// ✅ 正确 - 描述性的测试名称 Test func shouldReturnHandledWhenReceivingValidMessage(): Unit { // 测试实现 } Test func shouldThrowExceptionWhenMessageIsNull(): Unit { // 测试实现 } // ❌ 错误 - 不清晰的测试名称 Test func test1(): Unit { // 测试实现 }测试结构Arrange-Act-AssertTest func shouldProcessMessageCorrectly(): Unit { // Arrange - 准备测试数据 let actor TestActor() let message PingMessage(test) let context MockActorContext() // Act - 执行测试操作 let result actor.receive(message, context) // Assert - 验证结果 assertEquals(MessageResult.Handled, result) assertEquals(1, actor.getProcessedCount()) }实际仓库中单元测试基于仓颉 0.60.5 标准std.unittest框架编写。以 src/tests/unit/core/actor/simple_actor_test.cj 为例import std.unittest.* import std.unittest.testmacro.* Test public class SimpleActorTestSuite { private func createTestSystem(): CActorSystem { let timestamp DateTime.now().toUnixTimeStamp().toNanoseconds() CActorSystemFactory.create(simple-test-system-${timestamp}) } TestCase public func testActorSystemCreation(): Unit { let system createTestSystem() // 验证系统创建成功 Assert(!system.isTerminated(), true) Assert(system.getName().size 0, true) cleanupTestSystem(system) } }可以看到标准TestTestCaseAssert宏体系以及“创建资源 → 断言 → 清理”的固定骨架每个测试用例通过createTestSystem()/cleanupTestSystem()封装前后置逻辑避免在测试体内散落生命周期管理代码。此外仓库还为 Actor 场景专门建设了集成测试框架 src/integration/testing/test_framework.cj提供TestExpectationSuccess/Timeout/UnexpectedMessage/Error四种结果、TestTimeController虚拟时间推进便于确定性测试超时逻辑等工具cjpm.toml中cactor.integration.testing.*与cactor.examples.*系列包均被声明为executable输出类型对应可独立运行的集成测试与演示程序。文档规范模块 README、API 文档与变更日志指南对文档的要求分三条README 文件每个模块都应该有 README.md 文件包含功能描述、使用示例和 API 文档链接使用中文编写保持简洁明了API 文档所有公共接口都必须有完整的文档注释包含参数说明、返回值说明和使用示例并标注版本信息和作者信息变更日志记录所有重要变更按版本组织包含新功能、修复和破坏性变更使用语义化版本号。这些要求在仓库中有对应的实体文件文档目录 docs 提供中英文两套docs/zh、docs/en功能、部署、监控、故障排查等文档模块级说明以各目录下的README.md呈现如 src/examples/README.md、src/examples/hello_world_demo/README.mdAPI 注释要求与 src/core/actor/actor.cj 中Actor接口每个成员的/** */文档注释一致公共方法均带参数与返回值说明变更日志 CHANGELOG.md 声明格式基于 Keep a Changelog、项目遵循语义化版本按[版本号] - 日期组织分“新增功能 / 修复 / 破坏性变更”等小节记录与指南的三条要求逐条对应。代码审查清单提交前检查与审查要点指南给出两份可直接用于 PR 流程的清单。提交前检查作者自查代码符合命名约定添加了必要的注释和文档包含相应的单元测试通过所有现有测试性能没有明显下降没有引入新的编译警告遵循错误处理规范审查要点Reviewer 视角代码逻辑清晰易懂没有重复代码异常处理完善资源管理正确线程安全考虑边界条件处理结合 CActor 的技术栈最后三项权重更高无锁队列src/foundation/queue、邮箱与调度器src/runtime/mailbox、src/runtime/dispatcher都涉及无锁/并发结构“线程安全考虑”与“边界条件处理”是审查中需要重点核对的条目“资源管理正确”则对应 Actor 系统的启动/终止流程如测试中cleanupTestSystem对system.terminate()的调用。工具支持格式化与静态分析命令指南推荐了仓颉工具链的四条命令# 格式化 cj fmt src/ # 检查代码风格 cj lint src/ # 运行静态分析工具 cj analyze src/ # 检查潜在问题 cj check src/使用时需注意适用前提指南原文标注“如果可用”即cj fmt/cj lint等子命令依赖本机安装的仓颉工具链项目要求的cjc-version为 0.60.5见 cjpm.toml。编译侧的既有约定同样值得了解——cjpm.toml通过compile-option -Woff unused -Woff parser --diagnostic-formatnoColor关闭了部分警告并在目标平台如 aarch64-apple-darwin追加--cfg ohosfalse配置。日常开发中建议以“本地静态分析 现有测试全量通过”作为提交门槛与提交前检查清单保持一致。结语一份“活文档”的使用方式CActor 的代码风格指南末尾声明本指南是活文档会随项目发展和团队反馈持续更新。对贡献者而言建议的使用路径是以本文覆盖的命名/注释/结构/格式化规则为编码基线提交前对照双清单自查并以src/core、src/runtime、src/tests下的真实文件作为风格样板——src/core/actor/actor.cj接口与枚举、src/core/error/error_handling.cj错误分层、src/tests/unit/core/actor/simple_actor_test.cj单元测试骨架三个文件恰好覆盖了指南中的接口定义、错误处理与测试三类核心场景。遵循这套规范代码才能与 CActor 的分层架构foundation → core → runtime → api → patterns保持一致的可读性与可审查性。赞分享后端并发编程分布式【免费下载链接】cactor项目地址https://gitcode.com/Cangjie-SIG/cactor点击查看免费下载相关推荐DB-GPT 使用指南3 步让数据库听懂人话DB GPT 使用指南3 步让数据库听懂人话 业务同事想查「上周哪个区域卖得最好」可不会写 SQL找你跑数要等半天。DB GPT 就是为这种场景做的开源项人工智能AI 应用AI AgentRAG本地部署数据分析3分钟搞定RTL8188EU无线网卡Linux驱动安装完整指南3分钟搞定RTL8188EU无线网卡Linux驱动安装完整指南 还在为Linux系统无法识别RTL8188EU无线网卡而烦恼吗这款专为Realtek RTL驱动开发嵌入式网络FunClip终极指南免费开源AI视频智能剪辑工具完整教程FunClip终极指南免费开源AI视频智能剪辑工具完整教程 想象一下一小时的会议录像你只想留下某位发言人的三句话一整节网课你只想要讲重点的20秒。传统音视频语音人工智能AI 应用本地部署创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
后端并发编程分布式【免费下载链接】cactor项目地址https://gitcode.com/Cangjie-SIG/cactor点击查看免费下载本文基于 CActor 仓库的代码风格指南docs/CODE_STYLE_GUIDE.md系统讲解该项目面向仓颉Cangjie语言制定的全套编码规范命名约定、注释与文档规范、文件与类内部结构、格式化规则、错误处理模式、性能编码准则以及测试与审查流程。读完本文你可以在为 CActor 这类 Actor 系统贡献代码或阅读其源码时准确判断一段 Cangjie 代码是否符合项目惯例并理解每条规范背后的设计动机与在仓库中的实际落地方式。规范定位为什么 Actor 框架需要严格的代码风格CActor 是一个基于仓颉语言构建的高性能 Actor 系统仓库根部的 cjpm.toml 声明其当前版本为 7.0.0采用 6 层架构foundation / core / runtime / api / patterns / xstate依赖cjc-version 0.60.5编译器。项目由数十个 Cangjie 包构成每个包对应 src 下的一个目录并以pkg.cj声明包信息模块之间通过import互相引用。在这种多包、多层、多线程并发处理的代码库中统一风格的价值在于跨层可读性从 foundation 的队列/内存池到 runtime 的邮箱/调度器命名一致可以让读者快速定位符号语义并发安全可审查Actor 系统大量涉及无锁队列、状态标志位等并发结构规范的类内部结构与注释要求让线程安全问题在代码审查中更容易被发现工具化落地编译选项如compile-option -Woff unused ...与静态分析命令配合风格规则可以部分自动化检查。以下各节完整覆盖指南的每一条规则并结合仓库源码给出佐证。命名约定六种元素的命名标准指南将命名约定拆分为类名、接口名、函数名、变量名、常量名、包名六类每类均给出了正确与错误示例。类名与接口名PascalCase// ✅ 正确 class ActorSystem class MessageProcessor class ErrorHandlingManager interface Actor interface MessageHandler interface ErrorHandlingStrategy // ❌ 错误 class actorSystem interface messageHandler interface error_handling_strategy仓库源码完全符合这一约定。src/core/actor/actor.cj 中的Actor接口定义了receive、preStart、postStart、preStop、postStop、preRestart、postRestart等生命周期方法同文件的ActorLifecycleState枚举以| Created | Starting | Running | ...列出七种状态。src/core/error/error_handling.cj 中的CActorException、CActorErrorCode、ErrorSeverity也都是标准 PascalCase。函数名camelCase// ✅ 正确 func processMessage() func handleError() func createActorSystem() // ❌ 错误 func ProcessMessage() func handle_error() func CreateActorSystem()注意规则同时排除了 Java 风格的 PascalCase 函数名ProcessMessage与 C 风格的 snake_casehandle_error。源码中Actor接口的func receive(message: Message, context: ActorContext): MessageResultsrc/core/actor/actor.cj、error_handling.cj中的func getErrorCode()/func getSeverity()均遵循该规则。变量名camelCase// ✅ 正确 let messageCount: Int64 let processingTime: Duration let errorHandlingStrategy: ErrorHandlingStrategy // ❌ 错误 let MessageCount: Int64 let processing_time: Duration佐证src/tests/unit/core/actor/simple_actor_test.cj 中private var messageCount: Int32 0、private var lastMessage: String 是典型的双词 camelCase 成员变量。常量名SCREAMING_SNAKE_CASE// ✅ 正确 let MAX_MESSAGE_SIZE: Int64 1024 let DEFAULT_TIMEOUT: Duration Duration.second * 30 let ACTOR_SYSTEM_NAME: String CActor // ❌ 错误 let maxMessageSize: Int64 1024这一点在 CActor 的并发基础组件中体现得尤为明显——无锁队列与状态标志位全部使用大写常量// src/foundation/queue/lockfree_queue.cj public static let EMPTY: Int64 0 public static let FILLED: Int64 1 public static let WRITING: Int64 2 public static let READING: Int64 3 // src/runtime/actor/high_performance_actor.cj public static let RUNNING_FLAG: UInt32 0x01 public static let SUSPENDED_FLAG: UInt32 0x02 public static let STOPPED_FLAG: UInt32 0x04 public static let FAILED_FLAG: UInt32 0x08 public static let RESTARTING_FLAG: UInt32 0x10 public static let HIGH_PRIORITY_FLAG: UInt32 0x20可见 src/foundation/queue/lockfree_queue.cj、src/runtime/actor/high_performance_actor.cj 以及 src/runtime/mailbox/lockfree/lockfree_mailbox.cj 中状态机标志位与位掩码常量统一采用SCREAMING_SNAKE_CASE使并发语义在代码中一目了然。包名snake_case// ✅ 正确 package cactor.core.actor package cactor.runtime.dispatcher package cactor.patterns.ask // ❌ 错误 package cactor.Core.Actor该规则与仓库的实际包结构一一对应cjpm.toml 中package-configuration逐包声明了cactor.foundation.memory、cactor.foundation.queue、cactor.core.actor、cactor.runtime.mailbox、cactor.patterns.ask、cactor.xstate.core等包名全部小写点分层级层级顺序固定为“顶层cactor→ 层名foundation/core/runtime/api/patterns/xstate→ 子模块”。同时可以观察到各层包的产物类型约定foundation/core/api/patterns 层为staticruntime/macros 层为dynamic示例与集成测试包为executable这套约定也属于项目整体命名与组织规范的一部分。注释规范文档注释、行内注释与 TODO 体系类注释指南要求的类注释模板包含功能描述、设计背景与版本/作者元信息/** * Actor系统的核心实现 * * 负责管理Actor的生命周期、消息路由和系统配置。 * 参考Akka设计模式为仓颉语言量身定制。 * * since 1.0.0 * author CActor Team */ class CActorSystemImpl : ActorSystem { // 实现细节 }函数注释函数注释必须覆盖param、return、throws三类信息/** * 处理接收到的消息 * * param message 要处理的消息不能为null * param context Actor上下文包含发送者信息 * return 消息处理结果表示是否成功处理 * throws CActorException 当消息处理失败时抛出 */ func receive(message: Message, context: ActorContext): MessageResult { // 实现逻辑 }这一模板在 src/core/actor/actor.cj 中有真实落地Actor接口的receive方法注释正是“说明 param× 2 return”的标准形式/** * 处理接收到的消息 * param message 接收到的消息 * param context Actor上下文 * return 消息处理结果 */ func receive(message: Message, context: ActorContext): MessageResult行内注释与标记约定// 计算平均处理时间毫秒 let avgProcessingTime totalTime / messageCount // TODO: 实现更高效的消息路由算法 // FIXME: 修复并发访问时的竞态条件 // NOTE: 这里使用简化实现生产环境需要优化指南明确区分了TODO待实现、FIXME已知缺陷、NOTE实现取舍说明三种标记。在并发组件中NOTE类说明尤其重要——例如 src/foundation/queue/lockfree_queue.cj 这类无锁结构行内注释需要说明内存序或状态机转移的意图。文件头版权注释块结合下一条“文件组织”规则CActor 的每个源文件以统一的块注释开头。以 src/core/error/error_handling.cj 为例/* * Copyright (c) 2024. All rights reserved. * CActor 统一错误处理模块 * Plan 0.20 Phase 2.2: 错误处理标准化 - 统一错误处理实现 */ package cactor.core.error从源码结构看第三行还承载了项目规划信息Plan 编号 阶段 主题相当于把“这个文件为什么存在”直接写进了文件头这是 CActor 在通用版权头之上的自有扩展。代码结构文件组织与类内部布局文件组织顺序指南规定了源文件内元素的出现顺序版权头 →package声明 → 分组的import标准库 → CActor 核心模块 → 第三方库→ 类型定义 → 接口定义 → 类实现/* * Copyright (c) 2024. All rights reserved. * CActor - 文件功能描述 * 详细说明文件的作用和设计思路 */ package cactor.core.actor // 1. 标准库导入 import std.time.* import std.collection.* // 2. CActor核心模块导入 import cactor.core.message.* import cactor.core.context.* // 3. 第三方库导入如果有 // 4. 类型定义 public enum MessageResult { // 枚举值 } // 5. 接口定义 public interface Actor { // 接口方法 } // 6. 类实现 public class ActorImpl : Actor { // 类实现 }src/core/actor/actor.cj 是这一顺序的精确实例版权头 →package cactor.core.actor→import std.time.*→import cactor.core.message.*/import cactor.core.context.*→ 枚举ActorLifecycleState→ 接口Actor→ 类实现。类内部结构类内部的成员按固定顺序排列共六段class ExampleActor : Actor { // 1. 常量定义 private static let MAX_RETRIES: Int32 3 // 2. 属性定义 private var messageCount: Int64 0 private let startTime: Int64 // 3. 构造函数 public init() { this.startTime System.currentTimeMillis() } // 4. 公共属性 public prop name: String { get() { ExampleActor } } // 5. 公共方法 public func receive(message: Message, context: ActorContext): MessageResult { // 实现 } // 6. 私有方法 private func processMessage(message: Message): Unit { // 实现 } }测试代码中的SimpleTestActor展示了同一布局的真实形态src/tests/unit/core/actor/simple_actor_test.cjprivate var messageCount/private var lastMessage属性在前public prop name/public prop description公共只读属性居中receive公共方法与getMessageCount、reset查询/重置方法在后。属性使用 Cangjie 的propget()语法暴露只读视图而不是生成额外的 getter 方法这是与 Java 风格的关键差异。格式化规范缩进、行宽与空行缩进与空格统一使用 4 个空格缩进禁止 Tab 或混用// ✅ 正确 - 使用4个空格缩进 class Actor { func receive(message: Message): MessageResult { match (message) { case ping: PingMessage MessageResult.Handled case _ MessageResult.Unhandled } } }Cangjie 的match表达式是消息分发的惯用法case ... ...分支体与case对齐缩进两级src/tests/unit/core/actor/simple_actor_test.cj 中receive方法的match (message) { case msg: StringMessage ... case _ ... }即为标准写法。行长度单行不超过 120 字符超长参数列表应在参数之间换行每个参数独占一行// ✅ 正确 - 长行适当换行 let result processMessage( message, context, additionalParam, anotherParam )空行使用成员定义之间、逻辑块之间用空行分隔match的各个case分支之间以空行隔开class ExampleActor : Actor { private var count: Int64 0 public func receive(message: Message, context: ActorContext): MessageResult { count 1 match (message) { case ping: PingMessage handlePing(ping) MessageResult.Handled case pong: PongMessage handlePong(pong) MessageResult.Handled case _ MessageResult.Unhandled } } private func handlePing(ping: PingMessage): Unit { // 处理ping消息 } private func handlePong(pong: PongMessage): Unit { // 处理pong消息 } }这个“case 之间空行”的排版习惯同样出现在 src/core/actor/actor.cj 的ActorLifecycleState.toInt64()/fromInt64()等 match 块中。错误处理规范具体异常捕获与 Result/Option 返回异常处理必须捕获具体异常类型并按类型分支处理禁止空捕获// ✅ 正确 - 具体的异常处理 try { processMessage(message) } catch (e: CActorException) { // 处理CActor特定异常 handleCActorError(e) } catch (e: Exception) { // 处理通用异常 handleGenericError(e) } // ❌ 错误 - 捕获所有异常但不处理 try { processMessage(message) } catch (e: Exception) { // 空的异常处理 }这条规则与 CActor 的统一错误处理模块直接对应。src/core/error/error_handling.cj 定义了三层结构错误码枚举CActorErrorCode按位段划分错误域——系统级1000-1999、Actor 级2000-2999如ActorNotFoundError、ActorMailboxFullError、消息级3000-3999如MessageTimeoutError、网络级4000-4999、持久化5000-5999、集群6000-6999、通用9000-9999严重级别枚举ErrorSeverityCritical/High/Medium/Low/Info统一异常类CActorException : Exception携带errorCode、severity、timestamp与HashMapString, String形式的上下文并提供带 severity 与不带 severity默认Medium两个init重载。因此指南中catch (e: CActorException)的写法不是抽象示例而是指向该模块定义的真实类型。错误返回Result 与 Option指南推荐两种函数式返回模式// ✅ 正确 - 使用Result类型 func processMessage(message: Message): ResultUnit, CActorError { if (message.isValid()) { // 处理消息 Ok(()) } else { Err(CActorError.InvalidMessage(消息格式无效)) } } // ✅ 正确 - 使用Option类型 func findActor(name: String): OptionActorRef { if (actors.containsKey(name)) { Some(actors[name]) } else { None } }仓库中Option的使用有直接佐证测试框架的 src/integration/testing/test_framework.cj 中TestExpectation枚举的getValue()方法成功时返回Some(value)、失败返回None正是“用 Option 表达可能缺失的查询结果”这一规范的落地。性能规范对象重用与集合选型避免不必要的对象创建热点路径上的格式化操作应重用缓冲对象// ✅ 正确 - 重用对象 class MessageProcessor { private let stringBuilder: StringBuilder StringBuilder() func formatMessage(message: Message): String { stringBuilder.clear() stringBuilder.append(Message: ) stringBuilder.append(message.toString()) stringBuilder.toString() } } // ❌ 错误 - 频繁创建对象 func formatMessage(message: Message): String { let sb StringBuilder() // 每次都创建新对象 sb.append(Message: ) sb.append(message.toString()) sb.toString() }这一原则与 CActor 的 runtime 层设计目标一致——消息处理是每消息必走的热路径src/runtime 下存在 batching mailbox、对象池src/foundation/memory/object_pool.cj等配套机制来减少分配。高效的集合操作// ✅ 正确 - 预分配容量 let messages ArrayListMessage(expectedSize) // ✅ 正确 - 使用合适的集合类型 let actorIndex HashMapString, ActorRef() // 快速查找 let messageQueue ArrayDequeMessage() // 高效队列操作 // ❌ 错误 - 使用不合适的集合类型 let actorIndex ArrayListPairString, ActorRef() // 查找效率低选型要点可以概括为键值查找用HashMap如 Actor 注册表按名称查找ActorRef、FIFO 场景用ArrayDeque消息队列、邮箱底层、已知规模时通过构造函数预分配容量避免扩容。测试规范命名约定与 AAA 结构测试命名测试方法名必须描述“条件 预期行为”禁止test1这类无信息量命名// ✅ 正确 - 描述性的测试名称 Test func shouldReturnHandledWhenReceivingValidMessage(): Unit { // 测试实现 } Test func shouldThrowExceptionWhenMessageIsNull(): Unit { // 测试实现 } // ❌ 错误 - 不清晰的测试名称 Test func test1(): Unit { // 测试实现 }测试结构Arrange-Act-AssertTest func shouldProcessMessageCorrectly(): Unit { // Arrange - 准备测试数据 let actor TestActor() let message PingMessage(test) let context MockActorContext() // Act - 执行测试操作 let result actor.receive(message, context) // Assert - 验证结果 assertEquals(MessageResult.Handled, result) assertEquals(1, actor.getProcessedCount()) }实际仓库中单元测试基于仓颉 0.60.5 标准std.unittest框架编写。以 src/tests/unit/core/actor/simple_actor_test.cj 为例import std.unittest.* import std.unittest.testmacro.* Test public class SimpleActorTestSuite { private func createTestSystem(): CActorSystem { let timestamp DateTime.now().toUnixTimeStamp().toNanoseconds() CActorSystemFactory.create(simple-test-system-${timestamp}) } TestCase public func testActorSystemCreation(): Unit { let system createTestSystem() // 验证系统创建成功 Assert(!system.isTerminated(), true) Assert(system.getName().size 0, true) cleanupTestSystem(system) } }可以看到标准TestTestCaseAssert宏体系以及“创建资源 → 断言 → 清理”的固定骨架每个测试用例通过createTestSystem()/cleanupTestSystem()封装前后置逻辑避免在测试体内散落生命周期管理代码。此外仓库还为 Actor 场景专门建设了集成测试框架 src/integration/testing/test_framework.cj提供TestExpectationSuccess/Timeout/UnexpectedMessage/Error四种结果、TestTimeController虚拟时间推进便于确定性测试超时逻辑等工具cjpm.toml中cactor.integration.testing.*与cactor.examples.*系列包均被声明为executable输出类型对应可独立运行的集成测试与演示程序。文档规范模块 README、API 文档与变更日志指南对文档的要求分三条README 文件每个模块都应该有 README.md 文件包含功能描述、使用示例和 API 文档链接使用中文编写保持简洁明了API 文档所有公共接口都必须有完整的文档注释包含参数说明、返回值说明和使用示例并标注版本信息和作者信息变更日志记录所有重要变更按版本组织包含新功能、修复和破坏性变更使用语义化版本号。这些要求在仓库中有对应的实体文件文档目录 docs 提供中英文两套docs/zh、docs/en功能、部署、监控、故障排查等文档模块级说明以各目录下的README.md呈现如 src/examples/README.md、src/examples/hello_world_demo/README.mdAPI 注释要求与 src/core/actor/actor.cj 中Actor接口每个成员的/** */文档注释一致公共方法均带参数与返回值说明变更日志 CHANGELOG.md 声明格式基于 Keep a Changelog、项目遵循语义化版本按[版本号] - 日期组织分“新增功能 / 修复 / 破坏性变更”等小节记录与指南的三条要求逐条对应。代码审查清单提交前检查与审查要点指南给出两份可直接用于 PR 流程的清单。提交前检查作者自查代码符合命名约定添加了必要的注释和文档包含相应的单元测试通过所有现有测试性能没有明显下降没有引入新的编译警告遵循错误处理规范审查要点Reviewer 视角代码逻辑清晰易懂没有重复代码异常处理完善资源管理正确线程安全考虑边界条件处理结合 CActor 的技术栈最后三项权重更高无锁队列src/foundation/queue、邮箱与调度器src/runtime/mailbox、src/runtime/dispatcher都涉及无锁/并发结构“线程安全考虑”与“边界条件处理”是审查中需要重点核对的条目“资源管理正确”则对应 Actor 系统的启动/终止流程如测试中cleanupTestSystem对system.terminate()的调用。工具支持格式化与静态分析命令指南推荐了仓颉工具链的四条命令# 格式化 cj fmt src/ # 检查代码风格 cj lint src/ # 运行静态分析工具 cj analyze src/ # 检查潜在问题 cj check src/使用时需注意适用前提指南原文标注“如果可用”即cj fmt/cj lint等子命令依赖本机安装的仓颉工具链项目要求的cjc-version为 0.60.5见 cjpm.toml。编译侧的既有约定同样值得了解——cjpm.toml通过compile-option -Woff unused -Woff parser --diagnostic-formatnoColor关闭了部分警告并在目标平台如 aarch64-apple-darwin追加--cfg ohosfalse配置。日常开发中建议以“本地静态分析 现有测试全量通过”作为提交门槛与提交前检查清单保持一致。结语一份“活文档”的使用方式CActor 的代码风格指南末尾声明本指南是活文档会随项目发展和团队反馈持续更新。对贡献者而言建议的使用路径是以本文覆盖的命名/注释/结构/格式化规则为编码基线提交前对照双清单自查并以src/core、src/runtime、src/tests下的真实文件作为风格样板——src/core/actor/actor.cj接口与枚举、src/core/error/error_handling.cj错误分层、src/tests/unit/core/actor/simple_actor_test.cj单元测试骨架三个文件恰好覆盖了指南中的接口定义、错误处理与测试三类核心场景。遵循这套规范代码才能与 CActor 的分层架构foundation → core → runtime → api → patterns保持一致的可读性与可审查性。赞分享后端并发编程分布式【免费下载链接】cactor项目地址https://gitcode.com/Cangjie-SIG/cactor点击查看免费下载相关推荐DB-GPT 使用指南3 步让数据库听懂人话DB GPT 使用指南3 步让数据库听懂人话 业务同事想查「上周哪个区域卖得最好」可不会写 SQL找你跑数要等半天。DB GPT 就是为这种场景做的开源项人工智能AI 应用AI AgentRAG本地部署数据分析3分钟搞定RTL8188EU无线网卡Linux驱动安装完整指南3分钟搞定RTL8188EU无线网卡Linux驱动安装完整指南 还在为Linux系统无法识别RTL8188EU无线网卡而烦恼吗这款专为Realtek RTL驱动开发嵌入式网络FunClip终极指南免费开源AI视频智能剪辑工具完整教程FunClip终极指南免费开源AI视频智能剪辑工具完整教程 想象一下一小时的会议录像你只想留下某位发言人的三句话一整节网课你只想要讲重点的20秒。传统音视频语音人工智能AI 应用本地部署创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
