@linyjs/plugin-docs 0.0.13

package/docs/best-practices/naming-conventions.md

@@ -0,0 +1,496 @@
+# 命名规范
+
+本指南提供 linyjs 插件开发的命名规范和最佳实践。
+
+## 为什么需要命名规范?
+
+- 📖 **提高可读性** - 其他开发者能快速理解代码
+- 🔍 **便于搜索** - 统一的命名让查找更容易
+- 🛠️ **减少错误** - 避免命名冲突和混淆
+- 🤝 **团队协作** - 保持代码风格一致
+
+## 插件名称
+
+### 规则
+
+- 使用小写字母和连字符(`-`)
+- 以 `-plugin` 或 `-extension` 结尾(可选)
+- 描述性强,体现功能
+
+### 示例
+
+```typescript
+// ✅ 推荐
+name: 'blog-plugin'
+name: 'analytics-extension'
+name: 'payment-gateway'
+name: 'user-management'
+
+// ❌ 避免
+name: 'BlogPlugin'        // 使用驼峰
+name: 'my_plugin'         // 使用下划线
+name: 'plugin1'           // 不明确
+name: 'bp'                // 缩写不清
+```
+
+### package.json 中的命名
+
+```json
+{
+  "name": "@my-org/blog-plugin",
+  "version": "1.0.0"
+}
+```
+
+使用 scope(`@my-org/`)可以避免命名冲突。
+
+## Service Tag 命名
+
+### 规则
+
+- 使用 camelCase(小驼峰)
+- 体现服务类型和功能
+- 保持唯一性
+
+### 示例
+
+```typescript
+// ✅ 推荐 - 控制器
+serviceTag: 'articleController'
+serviceTag: 'userController'
+serviceTag: 'paymentController'
+
+// ✅ 推荐 - 中间件
+serviceTag: 'authMiddleware'
+serviceTag: 'loggingMiddleware'
+serviceTag: 'rateLimitMiddleware'
+
+// ✅ 推荐 - 服务
+serviceTag: 'articleService'
+serviceTag: 'emailService'
+serviceTag: 'cacheService'
+
+// ✅ 推荐 - 定时任务
+serviceTag: 'cleanupCron'
+serviceTag: 'reportCron'
+
+// ✅ 推荐 - 路由
+serviceTag: 'blogRoute'
+serviceTag: 'adminRoute'
+
+// ✅ 推荐 - 状态
+serviceTag: 'userState'
+serviceTag: 'appState'
+
+// ✅ 推荐 - 组件
+serviceTag: 'uiComponents'
+serviceTag: 'formComponents'
+
+// ✅ 推荐 - Hooks
+serviceTag: 'dataHooks'
+serviceTag: 'authHooks'
+
+// ❌ 避免
+serviceTag: 'ctrl'          // 缩写不清
+serviceTag: 's1'            // 无意义
+serviceTag: 'myService'     // 太通用
+serviceTag: 'Controller'    // 缺少具体功能
+```
+
+## 模块名称
+
+### 规则
+
+- 使用 camelCase
+- 区分服务端和客户端
+- 体现模块功能
+
+### 示例
+
+```typescript
+// ✅ 推荐 - 服务端模块
+export const blogServerModule: IModule = {
+  name: 'blogServer',
+  // ...
+};
+
+export const authServerModule: IModule = {
+  name: 'authServer',
+  // ...
+};
+
+// ✅ 推荐 - 客户端模块
+export const blogClientModule: IModule = {
+  name: 'blogClient',
+  // ...
+};
+
+export const adminClientModule: IModule = {
+  name: 'adminClient',
+  // ...
+};
+
+// ❌ 避免
+name: 'server'            // 太通用
+name: 'module1'           // 无意义
+name: 'BlogServerModule'  // 太长
+```
+
+## 路由路径
+
+### 规则
+
+- 使用小写字母和连字符
+- RESTful 风格
+- 资源名词复数形式
+
+### 示例
+
+```typescript
+// ✅ 推荐 - RESTful 风格
+path: '/api/articles'           // 获取文章列表
+path: '/api/articles/:id'       // 获取单篇文章
+path: '/api/users'              // 获取用户列表
+path: '/api/users/:id/posts'    // 获取用户的文章
+
+// ✅ 推荐 - 管理后台
+path: '/admin/dashboard'
+path: '/admin/settings'
+path: '/admin/users'
+
+// ❌ 避免
+path: '/api/getArticles'        // 动词在路径中
+path: '/api/Article'            // 大写
+path: '/api/article_list'       // 下划线
+path: '/api/articles123'        // 数字后缀
+```
+
+## 组件命名
+
+### 规则
+
+- 使用 PascalCase(大驼峰)
+- 描述性强
+- 体现组件用途
+
+### 示例
+
+```typescript
+// ✅ 推荐 - 页面组件
+function ArticleList() { }
+function ArticleDetail() { }
+function UserDashboard() { }
+function AdminSettings() { }
+
+// ✅ 推荐 - UI 组件
+function SubmitButton() { }
+function SearchInput() { }
+function LoadingSpinner() { }
+function ErrorMessage() { }
+
+// ✅ 推荐 - 布局组件
+function MainLayout() { }
+function SidebarMenu() { }
+function HeaderNav() { }
+
+// ❌ 避免
+function List() { }             // 太通用
+function Comp1() { }            // 无意义
+function articleList() { }      // 小写开头
+function Btn() { }              // 缩写不清
+```
+
+## 变量和函数命名
+
+### 规则
+
+- 使用 camelCase
+- 描述性强
+- 布尔值用 is/has/can 前缀
+
+### 示例
+
+```typescript
+// ✅ 推荐 - 变量
+const userName = 'John';
+const articleCount = 10;
+const isLoading = true;
+const hasPermission = false;
+const canEdit = true;
+
+// ✅ 推荐 - 函数
+function getUserById(id: number) { }
+function createArticle(data: any) { }
+function isValidEmail(email: string) { }
+function shouldUpdateCache() { }
+
+// ✅ 推荐 - 常量
+const MAX_RETRY_COUNT = 3;
+const API_BASE_URL = 'https://api.example.com';
+const DEFAULT_PAGE_SIZE = 10;
+
+// ❌ 避免
+const name = 'John';            // 不明确
+const cnt = 10;                 // 缩写
+const flag = true;              // 无意义
+function getData() { }          // 太通用
+function check() { }            // 不清楚检查什么
+```
+
+## 文件名
+
+### 规则
+
+- 使用 kebab-case(短横线)
+- 描述性强
+- 与导出内容对应
+
+### 示例
+
+```
+src/
+├── server/
+│   ├── controllers/
+│   │   ├── article-controller.ts    # ✅ 推荐
+│   │   └── user-controller.ts
+│   ├── services/
+│   │   ├── article-service.ts
+│   │   └── email-service.ts
+│   └── middlewares/
+│       ├── auth-middleware.ts
+│       └── logging-middleware.ts
+├── client/
+│   ├── pages/
+│   │   ├── article-list.tsx
+│   │   └── article-detail.tsx
+│   ├── components/
+│   │   ├── submit-button.tsx
+│   │   └── search-input.tsx
+│   └── hooks/
+│       ├── use-fetch-data.ts
+│       └── use-local-storage.ts
+└── shared/
+    └── types.ts
+
+// ❌ 避免
+articleController.ts        // 驼峰
+article_controller.ts       // 下划线
+ArticleController.ts        // 大写开头
+ctrl.ts                     // 缩写
+```
+
+## TypeScript 类型命名
+
+### 规则
+
+- 接口使用 PascalCase,以 `I` 开头(可选)
+- 类型别名使用 PascalCase
+- 枚举使用 PascalCase,成员全大写
+
+### 示例
+
+```typescript
+// ✅ 推荐 - 接口
+interface Article {
+  id: number;
+  title: string;
+}
+
+interface IUser {
+  id: number;
+  name: string;
+}
+
+// ✅ 推荐 - 类型别名
+type ArticleStatus = 'draft' | 'published' | 'archived';
+type UserRole = 'admin' | 'editor' | 'viewer';
+
+// ✅ 推荐 - 枚举
+enum HttpStatus {
+  OK = 200,
+  NOT_FOUND = 404,
+  INTERNAL_ERROR = 500
+}
+
+// ❌ 避免
+interface article { }         // 小写
+type article_status = ...;    // 下划线
+enum status { }               // 小写
+```
+
+## CSS 类名
+
+### 规则
+
+- 使用 kebab-case
+- BEM 命名法(可选)
+- 描述性强
+
+### 示例
+
+```css
+/* ✅ 推荐 - kebab-case */
+.article-list { }
+.article-item { }
+.submit-button { }
+
+/* ✅ 推荐 - BEM */
+.article-list { }
+.article-list__item { }
+.article-list__item--active { }
+.submit-button--disabled { }
+
+/* ❌ 避免 */
+.articleList { }              // 驼峰
+.article_list { }             // 下划线
+.item1 { }                    // 数字
+.red { }                      // 样式而非语义
+```
+
+## 环境变量
+
+### 规则
+
+- 全大写
+- 使用下划线分隔
+- 以插件名作为前缀
+
+### 示例
+
+```bash
+# ✅ 推荐
+BLOG_PLUGIN_API_KEY=xxx
+ANALYTICS_TRACKING_ID=xxx
+PAYMENT_STRIPE_SECRET=xxx
+
+# ❌ 避免
+apiKey=xxx                  # 小写
+API_KEY=xxx                 # 缺少前缀
+blog_plugin_apiKey=xxx      # 混合大小写
+```
+
+## 数据库集合名
+
+### 规则
+
+- 使用小写复数形式
+- 描述性强
+
+### 示例
+
+```typescript
+// ✅ 推荐
+db.collection('articles')
+db.collection('users')
+db.collection('comments')
+
+// ❌ 避免
+db.collection('Article')      // 大写
+db.collection('article')      // 单数
+db.collection('art')          // 缩写
+```
+
+## Git 分支命名
+
+### 规则
+
+- 使用 kebab-case
+- 前缀表明类型
+- 描述性强
+
+### 示例
+
+```bash
+# ✅ 推荐
+git checkout -b feature/add-blog-plugin
+git checkout -b fix/permission-bug
+git checkout -b docs/update-readme
+git checkout -b refactor/simplify-auth
+
+# ❌ 避免
+git checkout -b my-branch           # 不明确
+git checkout -b Feature_Blog        # 混合格式
+git checkout -b f1                  # 缩写
+```
+
+## Commit 消息
+
+### 规则
+
+- 使用祈使句
+- 首字母大写
+- 不超过 72 字符
+
+### 示例
+
+```bash
+# ✅ 推荐
+git commit -m "Add article CRUD operations"
+git commit -m "Fix permission check bug"
+git commit -m "Update documentation for slots"
+
+# ❌ 避免
+git commit -m "fixed bug"           # 过去式
+git commit -m "add stuff"           # 不明确
+git commit -m "Update the documentation for the slot feature"  # 太长
+```
+
+## 完整示例
+
+查看示例项目中的命名实践:
+
+- 📁 [Hello World 示例](../../examples/hello-world/)
+- 📁 [Blog Plugin 示例](../../examples/blog-plugin/)
+
+## 工具支持
+
+### ESLint 规则
+
+```json
+{
+  "rules": {
+    "@typescript-eslint/naming-convention": [
+      "error",
+      {
+        "selector": "variable",
+        "format": ["camelCase"]
+      },
+      {
+        "selector": "function",
+        "format": ["camelCase"]
+      },
+      {
+        "selector": "class",
+        "format": ["PascalCase"]
+      },
+      {
+        "selector": "interface",
+        "format": ["PascalCase"],
+        "prefix": ["I"]
+      }
+    ]
+  }
+}
+```
+
+### Prettier 配置
+
+```json
+{
+  "semi": true,
+  "trailingComma": "es5",
+  "singleQuote": true,
+  "printWidth": 80
+}
+```
+
+## 相关文档
+
+- ⚠️ [错误处理](./error-handling.md)
+- 📐 [ServiceDef 代码风格规范](./service-definition.md)
+- ⚡ [性能优化](./performance.md)
+- 🔒 [安全性](./security.md)
+
+---
+
+**上一篇**: [数据持久化](../guides/data-persistence.md) | **下一篇**: [ServiceDef 代码风格规范](./service-definition.md)