GitHub Copilot Rust 编码规范实战指南基于 awesome-copilot 社区指令的 Rust 高质量开发【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot本文以开源仓库 awesome-copilot 中的社区指令 instructions/rust.instructions.md 为主体系统讲解在 GitHub Copilot 辅助下编写 Rust 代码时应遵循的社区规范与最佳实践。你将掌握Copilot 在.rs文件上自动应用的编码准则所有权与借用、错误处理、API 设计、测试与文档、工程组织以及如何将这些准则落地到真实 Rust 项目如基于rmcpSDK 的 MCP 服务器开发中最终得到可读、安全、可维护且零告警的代码。指令文件在仓库中的定位与安装方式instructions/rust.instructions.md是 awesome-copilot 仓库中“Instructions自定义指令”资源的一种用于增强 GitHub Copilot 对特定技术栈的行为表现。该文件以 frontmatter 声明了其适用范围description: Rust programming language coding conventions and best practices applyTo: **/*.rs其中applyTo: **/*.rs是关键一旦将指令安装到工作区Copilot 就会在**所有 Rust 源文件.rs**的编辑与补全上下文中自动应用这套规范而无需手动提示。文件正文开篇即说明其准则来源Rust Book、Rust API Guidelines、RFC 430 命名约定以及 Rust 社区约定整体目标是“编写符合 Rust 惯例、社区标准的代码”。根据 docs/README.instructions.md 的说明这类指令的安装方式有两种将本文件内容复制到工作区的.github/copilot-instructions.md中使其全局生效创建任务级指令文件放在.github/instructions/目录下例如.github/instructions/rust-rules.instructions.md用于按场景精细化控制。安装后Copilot 在编写、审查、重构 Rust 代码时都会以本指令为行为基准。通用编码准则可读、安全、可维护指令文件首先给出了一组面向所有 Rust 代码的“总纲”这些准则是后续所有具体规范的上位原则始终优先可读性、安全性与可维护性代码首先是给人读的其次才是给机器执行的。使用强类型并充分发挥所有权ownership系统保障内存安全Rust 的核心优势在于编译期即可保证内存安全规范要求开发者在设计时主动利用这一点而不是依赖运行时检查。将复杂函数拆分为更小、更易管理的函数单个函数职责单一降低认知负担与测试难度。算法相关代码附带实现思路说明让读者以及 Copilot理解“为什么这样做”而非仅看到“做了什么”。以良好可维护性书写代码并为关键设计决策添加注释注释应解释决策动机而非复述代码。使用ResultT, E优雅处理错误并给出有意义的错误信息错误信息要能让调用者明白发生了什么、如何解决。对外部依赖在文档中说明其用途与目的避免出现“不知道某个 crate 为什么在这里”的依赖。遵循 RFC 430 命名约定类型、Trait、枚举用大驼峰UpperCamelCase函数、方法、变量、模块用小驼峰snake_case常量用全大写SCREAMING_SNAKE_CASE。编写符合借用检查器规则的原生、安全、高效的 Rust 代码。确保代码无告警编译告警往往是潜在问题的信号指令要求代码必须cargo build零告警。这些准则可以在本仓库的 agents/rust-mcp-expert.agent.md 与 instructions/rust-mcp-server.instructions.md 中看到一以贯之的实践例如“Type Safety First”“Idiomatic Rust: Follow Rust conventions and best practices”“Proper Error Handling: Use Result types and ErrorData”等原则正是上述总纲在 MCP 服务器开发场景中的具体化。推荐模式借用以取代克隆用类型表达意图指令文件列出的一系列“应当遵循的模式”构成了 Rust 日常开发的行为清单用模块mod与公开接口pub封装逻辑控制可见性避免实现细节泄漏。用?、match或if let正确处理错误?用于向上传播match/if let用于就地解构处理。用serde做序列化用thiserror或anyhow定义自定义错误thiserror适合库结构化、可枚举的错误类型anyhow适合应用与二进制快速上下文包装。通过实现 Trait 抽象服务或外部依赖让核心逻辑依赖抽象而非具体实现便于测试替换。用async/await组织异步代码运行时选择tokio或async-std。优先用枚举而非标志位/状态字面量枚举配合match可穷尽检查类型安全远优于bool/整数标志。复杂对象创建使用 Builder 模式避免超长构造参数列表。将二进制与库代码分离main.rsvslib.rs便于单元测试复用逻辑与跨 crate 复用。用rayon处理数据并行与 CPU 密集任务。用迭代器替代下标循环迭代器通常更快、更安全无越界风险。函数参数用str而非String当不需要所有权时。优先借用与零拷贝操作避免不必要的内存分配。所有权、借用与生命周期Ownership, Borrowing, and Lifetimes这是 Rust 区别于其他语言的核心模型指令文件给出了一组明确取舍场景推荐做法不需要转移所有权时优先借用T而不是克隆clone()需要修改被借用的数据时使用mut T编译器无法推断生命周期时显式标注生命周期参数如a单线程引用计数RcT多线程线程安全引用计数ArcT单线程内部可变性RefCellT多线程内部可变性MutexT或RwLockT从源码结构看这套模型在本仓库的 Rust 示例中被严格执行在 agents/rust-mcp-expert.agent.md 的状态管理示例中ServerState使用ArcRwLockT在异步多线程环境中安全共享计数器与缓存在 skills/rust-mcp-server-generator/SKILL.md 的src/state.rs模板中同样使用ArcRwLocki32并显式实现Clone正是“多线程用ArcRwLock”准则的直接落地。应避免的模式把错误处理当一等公民指令文件同样给出了明确的反面清单Patterns to Avoid用于约束 Copilot 不要生成“能跑但危险”的代码不要滥用unwrap()或expect()除非确有绝对把握如常量、测试中的固定输入否则一律走Result错误路径。库代码中避免 panic库的调用者无法控制 panic应返回Result让上层决策。不依赖全局可变状态用依赖注入或线程安全容器如ArcRwLockT、OnceLock、Mutex替代。避免过深嵌套逻辑用函数拆分或组合子combinator如Option::and_then、Result::map扁平化。不要忽略告警CI 中应将告警视为错误#![deny(warnings)]或cargo clippy -- -D warnings。避免unsafe除非确有必要且完整注释说明安全性不变量。不过度使用clone()优先借用除非确实需要所有权转移。避免过早collect()保持迭代器惰性直到确实需要集合时再物化。避免不必要的分配优先借用与零拷贝。这条“避免 unwrap/expect”的准则在仓库的 Rust 示例中体现得十分一致在 instructions/rust-mcp-server.instructions.md 的工具实现中除法工具对除零显式返回Err(Division by zero)而非 panic测试代码中unwrap()仅出现在#[tokio::test]断言场景如calculate(params).await.unwrap()这正是“测试中可用 unwrap业务代码必须用 Result”的边界示例。代码风格与格式化rustfmt 与 clippy 双保险指令文件对代码风格提出硬性要求Copilot 生成的代码应当天然符合遵循 Rust Style Guide使用rustfmt自动格式化cargo fmt应在提交前执行。单行尽量不超过 100 字符。函数与结构体文档紧贴声明之前使用//////即 rustdoc 注释会生成 API 文档。使用cargo clippy捕获常见错误并强制执行最佳实践clippy 内置大量 lint能发现冗余、性能问题与惯用性偏差。这三个工具fmt/clippy/test共同构成了指令文件结尾 Quality Checklist 中“Tooling”一栏的验收标准也是 Copilot 生成代码后开发者应当运行的验证闭环。错误处理ResultT, E与panic!的边界指令文件给出了完整的错误处理策略ResultT, E处理可恢复错误panic!仅用于不可恢复错误如不变量被破坏、显式声明的前置条件失败。优先用?运算符传播错误而不是unwrap()/expect()?自动转换错误类型并保留调用栈语义。用thiserror创建自定义错误类型或手动实现std::error::Error自定义错误应具备结构化字段便于上层分类处理。用OptionT表达“值可能存在也可能不存在”。提供有意义的错误信息与上下文例如anyhow::Context可为底层错误附加“读取哪个文件失败”等上下文。错误类型应良好且行为正确实现标准 trait至少实现Display与std::error::Error通常还应实现Send Sync。校验函数参数对非法输入返回对应错误而不是静默接受或 panic。在 instructions/rust-mcp-server.instructions.md 中可以看到这套策略的分层用法协议层错误使用rmcp::ErrorDataErrorData::invalid_params/ErrorData::internal_error应用层错误使用anyhow::Result配合.context(Failed to read config file)为错误补充上下文——两者互不混淆正是“错误类型有意义且分层”的实践样板。API 设计指南trait、类型安全与面向未来指令文件将 API 设计分为三个维度指导 Copilot 生成对外友好的公开接口。常见 Trait 的积极实现在合适的场景应主动实现以下标准 traitCopy、Clone、Eq、PartialEq、Ord、PartialOrd、Hash、Debug、Display、Default前六个表达值的可复制与可比性Debug用于调试输出指令在“面向未来”部分还要求所有公开类型必须实现DebugDisplay用于面向用户的文本输出Default提供合理的默认实例。标准转换 traitFrom、AsRef、AsMutFrom用于单向无损转换AsRef/AsMut用于轻量借用转换。集合类型应实现FromIterator与Extend使集合可以从迭代器构建collect()并增量扩展。注意Send与Sync由编译器在安全时自动实现除非涉及unsafe代码否则不要手动实现——这是对“尽量少碰 unsafe”原则的延伸。类型安全与可预测性使用 newtype 模式提供静态区分例如struct UserId(u64)而非裸u64让类型系统阻止“把订单 ID 当用户 ID 用”。参数应通过类型传达含义优先具体类型而非泛泛的bool参数例如用enum SortOrder { Asc, Desc }替代bool ascending避免“布尔参数地狱”。用OptionT恰当表达真正可选的参数。有明确接收者的函数应设计为方法self.method()比func(self)更符合直觉。只有智能指针才实现Deref/DerefMut避免滥用解引用魔法导致 API 行为难以预测。面向未来Future Proofing使用 sealed trait 防止下游自行实现通过将 trait 置于私有模块并依赖私有辅助 trait限制第三方实现范围为后续扩展保留空间。结构体字段设为私有通过构造方法/Builder 控制不变量字段公开会冻结演化空间。函数应校验其参数对非法输入快速失败。所有公开类型必须实现Debug这是调试与日志的底线要求。测试与文档#[cfg(test)]、tests/与 rustdoc指令文件要求 Copilot 生成具备完整测试与文档的代码用#[cfg(test)]模块与#[test]注解编写单元测试#[cfg(test)]确保测试代码仅编译于cargo test场景不进入发布产物。测试模块紧邻被测代码mod tests { ... }便于发现与维护也可直接访问私有成员。集成测试放在tests/目录文件名应具描述性集成测试从 crate 外部视角调用公开 API。为每个函数、结构体、枚举与复杂逻辑编写清晰简洁的注释。函数命名应具描述性并包含完整文档。用 rustdoc///文档化所有公开 API遵循 API Guidelines。用#[doc(hidden)]将实现细节从公开文档中隐藏如内部辅助类型、不应被下游依赖的实现细节。文档中说明错误条件、panic 场景与安全性考虑这是 rustdoc 高质量文档的三要素。示例代码使用?而非unwrap()或已废弃的try!宏因为文档示例会被复制粘贴示例本身就要示范正确写法。在 skills/rust-mcp-server-generator/SKILL.md 中可以看到这一套规范被完整模板化src/tools/example.rs内嵌#[cfg(test)] mod tests用#[tokio::test]测试工具函数tests/integration_test.rs从外部视角调用McpHandler::list_tools、call_tool、list_prompts、list_resources验证完整服务器交互——单元测试与集成测试分层清晰与指令要求完全吻合。工程组织Cargo.toml 元数据与模块划分指令文件对项目结构提出要求直接影响 Copilot 生成Cargo.toml与目录布局的方式Cargo.toml使用语义化版本semantic versioningMAJOR.MINOR.PATCH破坏性变更提升 MAJOR。包含完整元数据description、license、repository、keywords、categories便于 crate 被搜索与审计。使用 feature flags 提供可选功能如 skills/rust-mcp-server-generator/SKILL.md 的模板将 HTTP 传输相关依赖axum、tower-http设为optional true并挂到httpfeature 下默认构建不引入额外依赖。用mod.rs或命名文件组织模块按功能拆分子模块tools/、prompts/、resources/、state.rs并通过mod.rs统一导出。保持main.rs或lib.rs精简入口只做装配初始化日志、构建 handler、启动服务业务逻辑下沉到模块。instructions/rust-mcp-server.instructions.md 给出了一个完全符合上述要求的项目骨架main.rs仅负责tracing_subscriber初始化、ServerCapabilities声明与server.run(signal::ctrl_c())而handler.rs、tools/、prompts/、resources/各司其职tests/放置集成测试。质量清单发布或评审前的逐项验收指令文件以可勾选的 Checklist 收尾作为“发布或评审 Rust 代码前”的最终把关。这是 Copilot 生成代码后开发者自查的最小集合核心要求命名遵循 RFC 430 命名约定Trait在合适处实现Debug、Clone、PartialEq错误处理使用ResultT, E并提供有意义的错误类型文档所有公开项都有带示例的 rustdoc 注释测试覆盖充分包含边界情况如 instructions/rust-mcp-server.instructions.md 中除零用例test_divide_by_zero断言result.is_err()。安全与质量安全无多余unsafe代码错误处理得当性能高效使用迭代器最小化分配API 设计函数可预测、灵活、类型安全面向未来结构体字段私有适当使用 sealed trait工具链代码通过cargo fmt、cargo clippy、cargo test三项验证。规范落地实战用本套规范构建 Rust MCP 服务器为了让上文规范更具操作性下面以仓库中反复出现的“Rust rmcp SDK 构建 MCP 服务器”场景为例展示这套规范如何在真实代码中一一映射完整模板见 skills/rust-mcp-server-generator/SKILL.md 与 instructions/rust-mcp-server.instructions.md。依赖声明语义化版本与 feature flags[package] name my-mcp-server version 0.1.0 edition 2021 [dependencies] rmcp { version 0.8.1, features [server] } rmcp-macros 0.8 tokio { version 1, features [full] } serde { version 1.0, features [derive] } serde_json 1.0 anyhow 1.0 tracing 0.1 tracing-subscriber 0.3 schemars { version 0.8, features [derive] } async-trait 0.1 # 可选HTTP 传输 axum { version 0.7, optional true } tower-http { version 0.5, features [cors], optional true } [features] default [] http [dep:axum, dep:tower-http]这里体现了“工程组织”一节的多条规范语义化版本0.1.0、按功能拆分依赖rmcp只启用serverfeature、可选功能用 feature flags 隔离。工具函数Result错误处理 类型安全参数use rmcp::tool; use rmcp::model::Parameters; use serde::Deserialize; use schemars::JsonSchema; #[derive(Debug, Deserialize, JsonSchema)] pub struct DivideParams { pub a: f64, pub b: f64, } /// 执行除法运算除零时返回错误而非 panic #[tool(name divide, description Divides two numbers)] async fn divide(params: ParametersDivideParams) - Resultf64, String { let p params.inner(); if p.b 0.0 { Err(Cannot divide by zero.to_string()) } else { Ok(p.a / p.b) } }对照规范参数用Deserialize JsonSchema强类型化类型安全、错误返回Result而非 panic错误处理、///文档注释文档化、Debug派生常见 trait。共享状态ArcRwLockT多线程安全use std::sync::Arc; use tokio::sync::RwLock; #[derive(Clone)] pub struct ServerState { counter: ArcRwLocki32, } impl ServerState { pub fn new() - Self { Self { counter: Arc::new(RwLock::new(0)) } } pub async fn increment(self) - i32 { let mut counter self.counter.write().await; *counter 1; *counter } }对照“所有权、借用与生命周期”一节多线程共享状态选用ArcRwLockT工具通过self借用访问符合借用与线程安全准则。验证闭环fmt / clippy / test生成代码后按 Quality Checklist 的“工具链”要求执行cargo fmt # 格式化 cargo clippy -- -D warnings # lint且将告警视为错误 cargo test # 单元 集成测试将clippy的-D warnings与 CI 集成即可落实“不忽略告警CI 中视为错误”的避免清单。结语instructions/rust.instructions.md提供了一套以“安全、可读、可维护、类型驱动”为核心的 Rust 编码准则覆盖从命名、所有权、错误处理、API 设计到测试文档与工程组织的全链路。将它安装到工作区后GitHub Copilot 在编辑任何.rs文件时都会以这套规范为基准生成与审查代码配合cargo fmt、cargo clippy、cargo test三件套即可把规范从“书面约定”变为“可验证的工程实践”。如需进一步了解规范在具体项目中的落地可继续研读仓库内的 instructions/rust-mcp-server.instructions.md、agents/rust-mcp-expert.agent.md 与 skills/rust-mcp-server-generator/SKILL.md。【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 GitHub Copilot Rust 编码规范实战指南：基于 awesome-copilot 社区指令的 Rust 高质量开发
GitHub Copilot Rust 编码规范实战指南基于 awesome-copilot 社区指令的 Rust 高质量开发【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot本文以开源仓库 awesome-copilot 中的社区指令 instructions/rust.instructions.md 为主体系统讲解在 GitHub Copilot 辅助下编写 Rust 代码时应遵循的社区规范与最佳实践。你将掌握Copilot 在.rs文件上自动应用的编码准则所有权与借用、错误处理、API 设计、测试与文档、工程组织以及如何将这些准则落地到真实 Rust 项目如基于rmcpSDK 的 MCP 服务器开发中最终得到可读、安全、可维护且零告警的代码。指令文件在仓库中的定位与安装方式instructions/rust.instructions.md是 awesome-copilot 仓库中“Instructions自定义指令”资源的一种用于增强 GitHub Copilot 对特定技术栈的行为表现。该文件以 frontmatter 声明了其适用范围description: Rust programming language coding conventions and best practices applyTo: **/*.rs其中applyTo: **/*.rs是关键一旦将指令安装到工作区Copilot 就会在**所有 Rust 源文件.rs**的编辑与补全上下文中自动应用这套规范而无需手动提示。文件正文开篇即说明其准则来源Rust Book、Rust API Guidelines、RFC 430 命名约定以及 Rust 社区约定整体目标是“编写符合 Rust 惯例、社区标准的代码”。根据 docs/README.instructions.md 的说明这类指令的安装方式有两种将本文件内容复制到工作区的.github/copilot-instructions.md中使其全局生效创建任务级指令文件放在.github/instructions/目录下例如.github/instructions/rust-rules.instructions.md用于按场景精细化控制。安装后Copilot 在编写、审查、重构 Rust 代码时都会以本指令为行为基准。通用编码准则可读、安全、可维护指令文件首先给出了一组面向所有 Rust 代码的“总纲”这些准则是后续所有具体规范的上位原则始终优先可读性、安全性与可维护性代码首先是给人读的其次才是给机器执行的。使用强类型并充分发挥所有权ownership系统保障内存安全Rust 的核心优势在于编译期即可保证内存安全规范要求开发者在设计时主动利用这一点而不是依赖运行时检查。将复杂函数拆分为更小、更易管理的函数单个函数职责单一降低认知负担与测试难度。算法相关代码附带实现思路说明让读者以及 Copilot理解“为什么这样做”而非仅看到“做了什么”。以良好可维护性书写代码并为关键设计决策添加注释注释应解释决策动机而非复述代码。使用ResultT, E优雅处理错误并给出有意义的错误信息错误信息要能让调用者明白发生了什么、如何解决。对外部依赖在文档中说明其用途与目的避免出现“不知道某个 crate 为什么在这里”的依赖。遵循 RFC 430 命名约定类型、Trait、枚举用大驼峰UpperCamelCase函数、方法、变量、模块用小驼峰snake_case常量用全大写SCREAMING_SNAKE_CASE。编写符合借用检查器规则的原生、安全、高效的 Rust 代码。确保代码无告警编译告警往往是潜在问题的信号指令要求代码必须cargo build零告警。这些准则可以在本仓库的 agents/rust-mcp-expert.agent.md 与 instructions/rust-mcp-server.instructions.md 中看到一以贯之的实践例如“Type Safety First”“Idiomatic Rust: Follow Rust conventions and best practices”“Proper Error Handling: Use Result types and ErrorData”等原则正是上述总纲在 MCP 服务器开发场景中的具体化。推荐模式借用以取代克隆用类型表达意图指令文件列出的一系列“应当遵循的模式”构成了 Rust 日常开发的行为清单用模块mod与公开接口pub封装逻辑控制可见性避免实现细节泄漏。用?、match或if let正确处理错误?用于向上传播match/if let用于就地解构处理。用serde做序列化用thiserror或anyhow定义自定义错误thiserror适合库结构化、可枚举的错误类型anyhow适合应用与二进制快速上下文包装。通过实现 Trait 抽象服务或外部依赖让核心逻辑依赖抽象而非具体实现便于测试替换。用async/await组织异步代码运行时选择tokio或async-std。优先用枚举而非标志位/状态字面量枚举配合match可穷尽检查类型安全远优于bool/整数标志。复杂对象创建使用 Builder 模式避免超长构造参数列表。将二进制与库代码分离main.rsvslib.rs便于单元测试复用逻辑与跨 crate 复用。用rayon处理数据并行与 CPU 密集任务。用迭代器替代下标循环迭代器通常更快、更安全无越界风险。函数参数用str而非String当不需要所有权时。优先借用与零拷贝操作避免不必要的内存分配。所有权、借用与生命周期Ownership, Borrowing, and Lifetimes这是 Rust 区别于其他语言的核心模型指令文件给出了一组明确取舍场景推荐做法不需要转移所有权时优先借用T而不是克隆clone()需要修改被借用的数据时使用mut T编译器无法推断生命周期时显式标注生命周期参数如a单线程引用计数RcT多线程线程安全引用计数ArcT单线程内部可变性RefCellT多线程内部可变性MutexT或RwLockT从源码结构看这套模型在本仓库的 Rust 示例中被严格执行在 agents/rust-mcp-expert.agent.md 的状态管理示例中ServerState使用ArcRwLockT在异步多线程环境中安全共享计数器与缓存在 skills/rust-mcp-server-generator/SKILL.md 的src/state.rs模板中同样使用ArcRwLocki32并显式实现Clone正是“多线程用ArcRwLock”准则的直接落地。应避免的模式把错误处理当一等公民指令文件同样给出了明确的反面清单Patterns to Avoid用于约束 Copilot 不要生成“能跑但危险”的代码不要滥用unwrap()或expect()除非确有绝对把握如常量、测试中的固定输入否则一律走Result错误路径。库代码中避免 panic库的调用者无法控制 panic应返回Result让上层决策。不依赖全局可变状态用依赖注入或线程安全容器如ArcRwLockT、OnceLock、Mutex替代。避免过深嵌套逻辑用函数拆分或组合子combinator如Option::and_then、Result::map扁平化。不要忽略告警CI 中应将告警视为错误#![deny(warnings)]或cargo clippy -- -D warnings。避免unsafe除非确有必要且完整注释说明安全性不变量。不过度使用clone()优先借用除非确实需要所有权转移。避免过早collect()保持迭代器惰性直到确实需要集合时再物化。避免不必要的分配优先借用与零拷贝。这条“避免 unwrap/expect”的准则在仓库的 Rust 示例中体现得十分一致在 instructions/rust-mcp-server.instructions.md 的工具实现中除法工具对除零显式返回Err(Division by zero)而非 panic测试代码中unwrap()仅出现在#[tokio::test]断言场景如calculate(params).await.unwrap()这正是“测试中可用 unwrap业务代码必须用 Result”的边界示例。代码风格与格式化rustfmt 与 clippy 双保险指令文件对代码风格提出硬性要求Copilot 生成的代码应当天然符合遵循 Rust Style Guide使用rustfmt自动格式化cargo fmt应在提交前执行。单行尽量不超过 100 字符。函数与结构体文档紧贴声明之前使用//////即 rustdoc 注释会生成 API 文档。使用cargo clippy捕获常见错误并强制执行最佳实践clippy 内置大量 lint能发现冗余、性能问题与惯用性偏差。这三个工具fmt/clippy/test共同构成了指令文件结尾 Quality Checklist 中“Tooling”一栏的验收标准也是 Copilot 生成代码后开发者应当运行的验证闭环。错误处理ResultT, E与panic!的边界指令文件给出了完整的错误处理策略ResultT, E处理可恢复错误panic!仅用于不可恢复错误如不变量被破坏、显式声明的前置条件失败。优先用?运算符传播错误而不是unwrap()/expect()?自动转换错误类型并保留调用栈语义。用thiserror创建自定义错误类型或手动实现std::error::Error自定义错误应具备结构化字段便于上层分类处理。用OptionT表达“值可能存在也可能不存在”。提供有意义的错误信息与上下文例如anyhow::Context可为底层错误附加“读取哪个文件失败”等上下文。错误类型应良好且行为正确实现标准 trait至少实现Display与std::error::Error通常还应实现Send Sync。校验函数参数对非法输入返回对应错误而不是静默接受或 panic。在 instructions/rust-mcp-server.instructions.md 中可以看到这套策略的分层用法协议层错误使用rmcp::ErrorDataErrorData::invalid_params/ErrorData::internal_error应用层错误使用anyhow::Result配合.context(Failed to read config file)为错误补充上下文——两者互不混淆正是“错误类型有意义且分层”的实践样板。API 设计指南trait、类型安全与面向未来指令文件将 API 设计分为三个维度指导 Copilot 生成对外友好的公开接口。常见 Trait 的积极实现在合适的场景应主动实现以下标准 traitCopy、Clone、Eq、PartialEq、Ord、PartialOrd、Hash、Debug、Display、Default前六个表达值的可复制与可比性Debug用于调试输出指令在“面向未来”部分还要求所有公开类型必须实现DebugDisplay用于面向用户的文本输出Default提供合理的默认实例。标准转换 traitFrom、AsRef、AsMutFrom用于单向无损转换AsRef/AsMut用于轻量借用转换。集合类型应实现FromIterator与Extend使集合可以从迭代器构建collect()并增量扩展。注意Send与Sync由编译器在安全时自动实现除非涉及unsafe代码否则不要手动实现——这是对“尽量少碰 unsafe”原则的延伸。类型安全与可预测性使用 newtype 模式提供静态区分例如struct UserId(u64)而非裸u64让类型系统阻止“把订单 ID 当用户 ID 用”。参数应通过类型传达含义优先具体类型而非泛泛的bool参数例如用enum SortOrder { Asc, Desc }替代bool ascending避免“布尔参数地狱”。用OptionT恰当表达真正可选的参数。有明确接收者的函数应设计为方法self.method()比func(self)更符合直觉。只有智能指针才实现Deref/DerefMut避免滥用解引用魔法导致 API 行为难以预测。面向未来Future Proofing使用 sealed trait 防止下游自行实现通过将 trait 置于私有模块并依赖私有辅助 trait限制第三方实现范围为后续扩展保留空间。结构体字段设为私有通过构造方法/Builder 控制不变量字段公开会冻结演化空间。函数应校验其参数对非法输入快速失败。所有公开类型必须实现Debug这是调试与日志的底线要求。测试与文档#[cfg(test)]、tests/与 rustdoc指令文件要求 Copilot 生成具备完整测试与文档的代码用#[cfg(test)]模块与#[test]注解编写单元测试#[cfg(test)]确保测试代码仅编译于cargo test场景不进入发布产物。测试模块紧邻被测代码mod tests { ... }便于发现与维护也可直接访问私有成员。集成测试放在tests/目录文件名应具描述性集成测试从 crate 外部视角调用公开 API。为每个函数、结构体、枚举与复杂逻辑编写清晰简洁的注释。函数命名应具描述性并包含完整文档。用 rustdoc///文档化所有公开 API遵循 API Guidelines。用#[doc(hidden)]将实现细节从公开文档中隐藏如内部辅助类型、不应被下游依赖的实现细节。文档中说明错误条件、panic 场景与安全性考虑这是 rustdoc 高质量文档的三要素。示例代码使用?而非unwrap()或已废弃的try!宏因为文档示例会被复制粘贴示例本身就要示范正确写法。在 skills/rust-mcp-server-generator/SKILL.md 中可以看到这一套规范被完整模板化src/tools/example.rs内嵌#[cfg(test)] mod tests用#[tokio::test]测试工具函数tests/integration_test.rs从外部视角调用McpHandler::list_tools、call_tool、list_prompts、list_resources验证完整服务器交互——单元测试与集成测试分层清晰与指令要求完全吻合。工程组织Cargo.toml 元数据与模块划分指令文件对项目结构提出要求直接影响 Copilot 生成Cargo.toml与目录布局的方式Cargo.toml使用语义化版本semantic versioningMAJOR.MINOR.PATCH破坏性变更提升 MAJOR。包含完整元数据description、license、repository、keywords、categories便于 crate 被搜索与审计。使用 feature flags 提供可选功能如 skills/rust-mcp-server-generator/SKILL.md 的模板将 HTTP 传输相关依赖axum、tower-http设为optional true并挂到httpfeature 下默认构建不引入额外依赖。用mod.rs或命名文件组织模块按功能拆分子模块tools/、prompts/、resources/、state.rs并通过mod.rs统一导出。保持main.rs或lib.rs精简入口只做装配初始化日志、构建 handler、启动服务业务逻辑下沉到模块。instructions/rust-mcp-server.instructions.md 给出了一个完全符合上述要求的项目骨架main.rs仅负责tracing_subscriber初始化、ServerCapabilities声明与server.run(signal::ctrl_c())而handler.rs、tools/、prompts/、resources/各司其职tests/放置集成测试。质量清单发布或评审前的逐项验收指令文件以可勾选的 Checklist 收尾作为“发布或评审 Rust 代码前”的最终把关。这是 Copilot 生成代码后开发者自查的最小集合核心要求命名遵循 RFC 430 命名约定Trait在合适处实现Debug、Clone、PartialEq错误处理使用ResultT, E并提供有意义的错误类型文档所有公开项都有带示例的 rustdoc 注释测试覆盖充分包含边界情况如 instructions/rust-mcp-server.instructions.md 中除零用例test_divide_by_zero断言result.is_err()。安全与质量安全无多余unsafe代码错误处理得当性能高效使用迭代器最小化分配API 设计函数可预测、灵活、类型安全面向未来结构体字段私有适当使用 sealed trait工具链代码通过cargo fmt、cargo clippy、cargo test三项验证。规范落地实战用本套规范构建 Rust MCP 服务器为了让上文规范更具操作性下面以仓库中反复出现的“Rust rmcp SDK 构建 MCP 服务器”场景为例展示这套规范如何在真实代码中一一映射完整模板见 skills/rust-mcp-server-generator/SKILL.md 与 instructions/rust-mcp-server.instructions.md。依赖声明语义化版本与 feature flags[package] name my-mcp-server version 0.1.0 edition 2021 [dependencies] rmcp { version 0.8.1, features [server] } rmcp-macros 0.8 tokio { version 1, features [full] } serde { version 1.0, features [derive] } serde_json 1.0 anyhow 1.0 tracing 0.1 tracing-subscriber 0.3 schemars { version 0.8, features [derive] } async-trait 0.1 # 可选HTTP 传输 axum { version 0.7, optional true } tower-http { version 0.5, features [cors], optional true } [features] default [] http [dep:axum, dep:tower-http]这里体现了“工程组织”一节的多条规范语义化版本0.1.0、按功能拆分依赖rmcp只启用serverfeature、可选功能用 feature flags 隔离。工具函数Result错误处理 类型安全参数use rmcp::tool; use rmcp::model::Parameters; use serde::Deserialize; use schemars::JsonSchema; #[derive(Debug, Deserialize, JsonSchema)] pub struct DivideParams { pub a: f64, pub b: f64, } /// 执行除法运算除零时返回错误而非 panic #[tool(name divide, description Divides two numbers)] async fn divide(params: ParametersDivideParams) - Resultf64, String { let p params.inner(); if p.b 0.0 { Err(Cannot divide by zero.to_string()) } else { Ok(p.a / p.b) } }对照规范参数用Deserialize JsonSchema强类型化类型安全、错误返回Result而非 panic错误处理、///文档注释文档化、Debug派生常见 trait。共享状态ArcRwLockT多线程安全use std::sync::Arc; use tokio::sync::RwLock; #[derive(Clone)] pub struct ServerState { counter: ArcRwLocki32, } impl ServerState { pub fn new() - Self { Self { counter: Arc::new(RwLock::new(0)) } } pub async fn increment(self) - i32 { let mut counter self.counter.write().await; *counter 1; *counter } }对照“所有权、借用与生命周期”一节多线程共享状态选用ArcRwLockT工具通过self借用访问符合借用与线程安全准则。验证闭环fmt / clippy / test生成代码后按 Quality Checklist 的“工具链”要求执行cargo fmt # 格式化 cargo clippy -- -D warnings # lint且将告警视为错误 cargo test # 单元 集成测试将clippy的-D warnings与 CI 集成即可落实“不忽略告警CI 中视为错误”的避免清单。结语instructions/rust.instructions.md提供了一套以“安全、可读、可维护、类型驱动”为核心的 Rust 编码准则覆盖从命名、所有权、错误处理、API 设计到测试文档与工程组织的全链路。将它安装到工作区后GitHub Copilot 在编辑任何.rs文件时都会以这套规范为基准生成与审查代码配合cargo fmt、cargo clippy、cargo test三件套即可把规范从“书面约定”变为“可验证的工程实践”。如需进一步了解规范在具体项目中的落地可继续研读仓库内的 instructions/rust-mcp-server.instructions.md、agents/rust-mcp-expert.agent.md 与 skills/rust-mcp-server-generator/SKILL.md。【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考