Spring Boot 开发的 Kotlin 编码最佳实践

项目结构与组织

1. 将你的源代码分组到明确定义的包中，如 controller、service、repository 和 model，以分离关注点并提高可维护性。
2. 组织你的文件系统，使每个目录都镜像 Kotlin 的包名（例如，将 com.myapp.users 放在 src/main/kotlin/com/myapp/users 下）。
3. 每个 Kotlin 文件都以其包含的主要类或概念命名，以使代码库更易于导航和理解。
4. 避免使用像 Utils.kt 这样模糊的文件名；相反，使用简洁且有意义的名称，以反映文件内容的目的。
5. 将你的 Spring Boot 应用程序入口点放在根包中，并按层或功能组织子包，以帮助 Spring 高效地扫描和组织组件。

编码风格与约定

1. 类和对象名使用 PascalCase，函数和变量名使用 camelCase，常量名使用 UPPER_SNAKE_CASE，以遵循 Kotlin 的命名约定并提高可读性。
2. 默认使用 val 声明变量，仅在需要可变性时才使用 var，以促进更安全、更可预测的代码。

   val maxConnections = 10    // 不可变引用
   var currentUsers = 0       // 可变的，如果可能，尽量避免
   

3. 将变量的作用域限制在其实际使用的地方——函数内部或更小的代码块中——以避免意外误用，并使代码更易于遵循。
4. 使用 4 空格缩进、在运算符和逗号周围使用适当的间距，以及编写简短、专注的函数来统一格式化你的代码，以提高清晰度和可维护性。
5. 编写清晰且富有表现力的代码，而不是巧妙的单行代码；将复杂的逻辑分解为中间变量或命名良好的函数，以提高可读性。
6. 为类、函数和变量使用描述性的名称以传达意图，并避免使用像 '-Manager' 或 '-Helper' 这样没有实际意义的模糊后缀。
7. 保持属性的 getter 和 setter 简单且不含复杂逻辑；如果需要复杂的行为，请将其移至单独的方法中，以保持属性访问的可预测性。

地道的 Kotlin 用法

1. 使用数据类（data class）定义 DTO 和实体，这样你就可以获得像 equals() 和 copy() 这样的有用方法，而无需编写样板代码。
2. 使用默认参数和命名参数替换重载的构造函数，以简化函数调用并使其更具表现力。

   // Kotlin – 使用默认参数
   fun createConnection(host: String, secure: Boolean = true) { … }
   
   createConnection("example.com")                      // 使用默认的 secure=true
   createConnection(host = "test.com", secure = false)  // 使用命名参数以提高清晰度
   

3. 使用 when 表达式代替冗长的 if-else 链，以编写更清晰、更易读的条件逻辑，从而清楚地处理每种情况。
4. 创建扩展函数而不是工具类，以更自然、更易读的方式为现有类型添加可重用行为。

   fun String.capitalizeFirst(): String = replaceFirstChar { it.uppercaseChar() }
   
   println("kotlin".capitalizeFirst())  // 打印 "Kotlin"
   

5. 使用作用域函数如 apply、let、also、run 和 with 来减少重复，并清晰地表达对象配置或空安全操作。
6. 仅在必要时将变量声明为可空，并使用安全调用运算符（?.）和 Elvis 运算符（?:）来处理它们，以避免运行时崩溃。
7. 避免使用非空断言（!!），而是提供回退值或显式的空检查，以编写更安全、更可预测的代码。
8. 立即处理来自 Java API 的平台类型，通过将它们显式转换为 String 或 String?，以避免在你的 Kotlin 代码中传播可空性的不确定性。
9. 使用 Kotlin 的函数式集合操作如 filter、map 和 forEach 代替手动循环，以编写简洁且富有表现力的数据转换逻辑。

   // 命令式方法
   val activeUsers = mutableListOf<User>()
   for (user in users) {
       if (user.isActive) activeUsers.add(user)
   }
   
   // 地道的函数式方法
   val activeUsers = users.filter { it.isActive }
   

10. 当逻辑清晰时，将简单函数转换为单表达式函数，以消除不必要的语法并提高代码的简洁性。

    fun toDto(entity: User) = UserDto(name = entity.name, email = entity.email)
    

11. 使用字符串模板（$var 或 ${expression}）构建字符串，而不是使用拼接，并使用三引号字符串处理干净的多行文本。

实现模式与设计

1. 通过构造函数参数使用 val 注入依赖，以保持其不可变性，并与 Spring 和 Kotlin 的习惯用法保持一致。

   @Service
   class OrderService(
       private val orderRepo: OrderRepository,
       private val notifier: Notifier
   ) {
       // ...
   }
   

2. 默认保持类为 final，并让 Spring 的 'all-open' 插件处理代理生成，这样你就不需要手动添加 open 修饰符。
3. 使用 Kotlin 的 object 声明来实现真正的单例或无状态的工具持有者，而不是使用静态方法或 Java 风格的单例。
4. 通过组合小的、专注的类或使用高阶函数来支持组合，而不是依赖于深层的继承层次结构。
5. 当一个类型有一个有限的、封闭的变体集时，定义密封类（sealed class），以在 when 表达式中强制进行详尽的处理并提高类型安全性。

   sealed class Result<out T>
   data class Success<T>(val data: T): Result<T>()
   data class Error(val exception: Throwable): Result<Nothing>()
   

6. 使用枚举类（enum class）来建模可能包含逻辑的固定常量集，避免在业务逻辑中使用魔术字符串或原始值。
7. 对于"未找到"或"无效输入"等预期场景，返回可空类型、密封类或结果包装器，而不是抛出异常。
8. 始终使用 use 函数来安全地管理和关闭像流和文件句柄这样的资源，确保即使发生异常也能关闭它们。

   FileInputStream("data.txt").use { stream ->
       // 从流中读取
   } // 流在这里自动关闭
   

9. 尽可能使用 private 或 internal 来最小化组件的可见性，只将真正必要的内容公开为 public。
10. 使用 Kotlin 协程和挂起函数（suspend functions）以及像 launch 或 async 这样的协程构建器来编写干净的、无回调地狱的异步后端代码。
11. 利用 Kotlin 的标准库特性，如 lazy、observable、infix 和运算符重载，来编写简洁、富有表现力且地道的代码。
12. 使用带有 val 字段的不可变数据类实体和 Kotlin 的 JPA 插件，以满足 JPA 的要求，同时保持模型的安全性和线程友好性。
13. 使用依赖注入和纯函数为你的业务逻辑编写单元测试，以使测试简单且独立于 Spring 的上下文。

Awesome Cursor Rules 中文版

🇨🇳 中文 | 🇺🇸 English

为中文开发者打造的 Cursor AI 编程规则集合 Chinese localized version of Awesome Cursor Rules

132 个规则文件 · 32 个技术领域 · 190 个技术文档 · 6,500+ 行代码

🚀 快速开始 · 📂 规则目录 · 💡 使用指南 · 📚 官网 · 🤝 贡献

---

📋 目录

• 这是什么？
• 什么是 .cursorrules？
• ✨ 特性亮点
• 🚀 快速开始
• 📂 规则目录
• 💡 使用指南
• 📊 数据统计
• 📚 文档
• 🤝 贡献
• 📄 许可证

---

这是什么？

Awesome Cursor Rules 是优秀的 Cursor AI 编程助手规则集合。本项目是其中文本地化版本，专为中文开发者优化：

• 🎯 精准翻译 — 高质量中文翻译，技术术语准确专业
• 📂 结构清晰 — 按技术领域分类，便于快速查找
• 🚀 开箱即用 — 复制 .cursorrules 文件即可开始使用
• 🌍 双语支持 — 完整的中英文文档对照
• ⚡ 132 个规则 — 涵盖前端、后端、移动端、AI、DevOps 等

🌐 在线文档: awesome-cursorrules-zh.js.org

---

什么是 .cursorrules？

.cursorrules 是 Cursor AI 编辑器的项目级配置文件，用于定义 AI 如何协助你的编程：

功能	说明	示例
编码规范	定义代码风格、命名约定	PascalCase 组件名、camelCase 函数名
技术栈	指定框架、库、工具链	React + TypeScript + Tailwind CSS
最佳实践	自动应用行业标准	错误处理、性能优化、安全策略
AI 行为	定制 AI 回复和代码生成风格	详细注释、函数式编程

💡 本质：给 AI 助手的"项目工作手册"，确保代码生成的一致性和高质量

---

✨ 特性亮点

🏆 热门技术栈

📊 覆盖领域

• 🌐 应用开发: 前端、后端、移动端、数据库、系统编程
• 🤖 AI 与数据: 机器学习、数据科学、数据工程
• ☁️ 基础设施: DevOps、云服务、边缘计算、安全
• 🔬 专业领域: 区块链、物联网、量子计算、生物科技

---

🚀 快速开始

安装使用

# 克隆仓库
git clone https://github.com/LessUp/awesome-cursorrules-zh.git

# 浏览可用规则
cd awesome-cursorrules-zh
ls rules/frontend/react/

使用方法

# 复制规则到你的项目
cp rules/frontend/react/nextjs-typescript/.cursorrules /你的项目路径/

完成！在 Cursor 中打开项目，AI 将自动遵循规则。

热门规则示例

技术栈	规则	命令
Next.js + TypeScript	nextjs-typescript	cp rules/frontend/react/nextjs-typescript/.cursorrules ./
Vue 3	composition-api	cp rules/frontend/vue/composition-api/.cursorrules ./
FastAPI	fastapi-api-example	cp rules/backend/python/fastapi-api-example/.cursorrules ./
Flutter	flutter-app-expert	cp rules/mobile/flutter/flutter-app-expert/.cursorrules ./

📖 完整快速开始指南

---

📂 规则目录

领域	目录	技术
前端	frontend/	React, Vue, Angular, Svelte, SolidJS, TypeScript
后端	backend/	Node.js, Python, Go, Java, PHP, .NET, Elixir
移动端	mobile/	Flutter, React Native, SwiftUI, Jetpack Compose
数据库	database/	云原生、时空数据库
系统编程	systems/	C++ 现代规范、Rust

领域	目录	技术
AI/ML	ai/	计算机视觉、MLOps、知识图谱、边缘 AI
数据科学	data-science/	Pandas, PyTorch, TensorFlow, Scikit-learn
数据工程	data/	Kafka, Spark, Flink, 数据仓库

领域	目录	技术
DevOps	devops/	Docker, Kubernetes, Terraform, CI/CD
云服务	cloud/	中间件、无服务器
边缘计算	edge/	AI 推理、模型压缩
安全	security/	零信任、隐私计算、同态加密

领域	目录	技术
区块链	blockchain/	Solidity, Web3, 智能合约, Foundry
物联网	iot/	嵌入式、数字孪生
量子计算	quantum/	量子纠错、超导计算
生物科技	bio/	生物电子、生物传感器
硬件	hardware/	神经形态芯片、光子计算
游戏开发	gaming/	DragonRuby, 云游戏

领域	目录	技术
开发工具	tools/	Convex, GitHub Quality
通用规范	general/	代码规范、风格一致性、测试

完整目录请查看 rules/ 文件夹

---

💡 使用指南

单技术栈项目

cp rules/frontend/react/nextjs-typescript/.cursorrules ./

多技术栈项目

方案一：合并规则

cat rules/frontend/react/nextjs-typescript/.cursorrules > .cursorrules
echo "" >> .cursorrules
cat rules/backend/python/fastapi-api-example/.cursorrules >> .cursorrules

方案二：目录级规则（推荐用于单体仓库）

project/
├── .cursorrules           # 通用规则
├── frontend/
│   └── .cursorrules       # 前端规则
└── backend/
    └── .cursorrules       # 后端规则

自定义规则

# 追加项目特定规则
cat >> .cursorrules << 'EOF'

## 项目自定义规则
- API 路由使用 /api/v1 前缀
- 所有模型必须包含 created_at 和 updated_at 字段
- 优先使用函数组件而非类组件
EOF

📖 完整最佳实践指南

---

📊 数据统计

指标	数值
规则文件	132 个 .cursorrules
技术领域	32 个分类
技术文档	190 个 Markdown 文件
总行数	6,500+ 行
翻译进度	100% 中英双语
覆盖范围	前端、后端、移动端、AI、DevOps、区块链、物联网等

热门技术

TypeScript  ████████████████████████████████  29 个规则
React       ██████████████████████            19 个规则
Tailwind    ███████████████                   13 个规则
Python      █████████████                     11 个规则
Next.js     ██████████                         8 个规则
Node.js     █████████                          7 个规则
Docker      █████████                          7 个规则

---

📚 文档

文档	说明	链接
🚀 快速开始	5 分钟上手指南	在线阅读 · GitHub
📖 安装指南	详细安装配置	在线阅读 · GitHub
💡 最佳实践	配置和使用建议	在线阅读 · GitHub
🔧 故障排除	问题诊断解决	在线阅读 · GitHub
📋 API 参考	规则格式参考	在线阅读 · GitHub
📝 更新日志	版本历史	中文 · English

---

🤝 贡献

欢迎所有形式的贡献：

• 🐛 报告问题 — 提交 Issue
• 🔧 改进内容 — 提交 Pull Request
• 🔄 同步上游 — 帮助与原项目保持同步
• 📝 完善文档 — 优化使用指南

详见 贡献指南

---

🙏 致谢

本项目是 PatrickJS/awesome-cursorrules 的中文本地化版本。感谢原作者和所有贡献者。

---

📄 许可证

MIT License

---

如果这个项目对你有帮助，请给一个 ⭐ Star！

🌐 访问官方网站 · ⬆ 返回顶部