@linyjs/plugin-docs 0.0.13

package/docs/best-practices/service-definition.md

@@ -0,0 +1,332 @@
+# ServiceDef 代码风格规范
+
+本指南介绍 linyjs 插件开发中 `ServiceDef` 的两条核心代码风格规范，确保代码组织一致、可读、易维护。
+
+## 为什么需要规范?
+
+- 📖 **提高可读性** — 服务定义与实现放在一起，一目了然
+- 🔍 **便于查找** — 看到类就能找到它的 ServiceDef，反之亦然
+- 🛠️ **减少错误** — 独立声明减少缩进层级，避免括号匹配错误
+- 🤝 **团队协作** — 统一风格，降低 review 沟通成本
+
+---
+
+## 规则一：ServiceDef 必须声明为独立变量
+
+### 规则说明
+
+`ServiceDef` 必须先声明为独立变量，然后在 `serviceDefs` 数组中通过变量名引用。**禁止**将 `ServiceDef` 对象字面量直接内联在 `serviceDefs` 数组中。
+
+### ✅ 正确写法
+
+```typescript
+import type { IModule, IServiceDef } from '@linyjs/server-module-interface';
+
+class HelloController {
+  getRoutes() {
+    return [/* ... */];
+  }
+}
+
+const helloControllerDef: IServiceDef = {
+  serviceTag: 'helloController',
+  serviceImpl: HelloController,
+  meta: { usageType: 'controller' }
+};
+
+export const helloServerModule: IModule = {
+  name: 'helloServer',
+  serviceDefs: [helloControllerDef]
+};
+```
+
+### ❌ 错误写法
+
+```typescript
+import type { IModule } from '@linyjs/server-module-interface';
+
+class HelloController {
+  getRoutes() {
+    return [/* ... */];
+  }
+}
+
+export const helloServerModule: IModule = {
+  name: 'helloServer',
+  serviceDefs: [
+    {
+      serviceTag: 'helloController',
+      serviceImpl: HelloController,
+      meta: { usageType: 'controller' }
+    }
+  ]
+};
+```
+
+### 原因
+
+| 对比项 | 独立变量声明 | 内联在数组中 |
+|--------|------------|------------|
+| 缩进层级 | 浅（2层） | 深（4层+） |
+| 可读性 | 高，变量名即语义 | 低，大段对象字面量淹没模块声明 |
+| 复用性 | 可被多个模块引用 | 无法复用 |
+| 维护性 | 修改时不影响模块声明 | 修改时需在数组中定位 |
+
+---
+
+## 规则二：ServiceDef 声明必须与实现类放在同一个文件中
+
+### 规则说明
+
+`ServiceDef` 声明必须紧挨着它的 `serviceImpl` 实现类，放在同一个文件中。**禁止**将 `ServiceDef` 和实现类分离到不同文件，然后在模块入口文件中重新声明。
+
+### ✅ 正确写法
+
+**`src/server/services/article-controller.ts`**
+
+```typescript
+import type { IControllerService, IControllerServiceDef } from '@linyjs/server-module-interface';
+
+export class ArticleController implements IControllerService {
+  getRoutes() {
+    return [/* ... */];
+  }
+}
+
+export const articleControllerDef: IControllerServiceDef = {
+  serviceTag: 'articleController',
+  serviceImpl: ArticleController,
+  dependencies: ['mdb.mongoDBService'],
+  meta: { usageType: 'controller' }
+};
+```
+
+**`src/server/server-module.ts`**
+
+```typescript
+import type { IModule } from '@linyjs/server-module-interface';
+import { articleControllerDef } from './services/article-controller.js';
+
+export const articleServerModule: IModule = {
+  name: 'articleServer',
+  moduleDependencies: ['mdb'],
+  serviceDefs: [articleControllerDef]
+};
+```
+
+### ❌ 错误写法
+
+**`src/server/services/article-controller.ts`** — 只有类，没有 ServiceDef
+
+```typescript
+export class ArticleController implements IControllerService {
+  getRoutes() {
+    return [/* ... */];
+  }
+}
+```
+
+**`src/server/server-module.ts`** — ServiceDef 与类分离
+
+```typescript
+import { ArticleController } from './services/article-controller.js';
+
+const articleControllerDef: IControllerServiceDef = {
+  serviceTag: 'articleController',
+  serviceImpl: ArticleController,
+  dependencies: ['mdb.mongoDBService'],
+  meta: { usageType: 'controller' }
+};
+
+export const articleServerModule: IModule = {
+  name: 'articleServer',
+  moduleDependencies: ['mdb'],
+  serviceDefs: [articleControllerDef]
+};
+```
+
+### 原因
+
+| 对比项 | 同文件放置 | 分离到不同文件 |
+|--------|----------|-------------|
+| 内聚性 | 高，定义与实现在一起 | 低，需跨文件查找 |
+| 修改成本 | 低，改一处即可 | 高，可能漏改 |
+| 文件职责 | 清晰，每个文件自包含 | 模糊，入口文件混杂声明 |
+
+---
+
+## 完整示例
+
+以下是一个完整的服务端模块示例，遵循两条规范：
+
+### 项目结构
+
+```
+src/server/
+├── controllers/
+│   └── article-controller.ts   # ArticleController 类 + articleControllerDef
+├── middleware/
+│   └── auth-middleware.ts       # AuthMiddleware 类 + authMiddlewareDef
+├── services/
+│   └── article-service.ts       # ArticleService 类 + articleServiceDef
+└── server-module.ts             # 模块入口，只做导入和组装
+```
+
+### 控制器文件
+
+**`src/server/controllers/article-controller.ts`**
+
+```typescript
+import type { IControllerService, IControllerServiceDef } from '@linyjs/server-module-interface';
+
+export class ArticleController implements IControllerService {
+  getRoutes() {
+    return [
+      {
+        method: 'GET' as const,
+        path: '/api/articles',
+        middlewares: [],
+        responseType: 'json' as const,
+        handler: async () => {
+          return { articles: [] };
+        }
+      }
+    ];
+  }
+}
+
+export const articleControllerDef: IControllerServiceDef = {
+  serviceTag: 'articleController',
+  serviceImpl: ArticleController,
+  dependencies: ['articleService'],
+  meta: { usageType: 'controller' }
+};
+```
+
+### 中间件文件
+
+**`src/server/middleware/auth-middleware.ts`**
+
+```typescript
+import type { IMiddlewareService, IMiddlewareServiceDef } from '@linyjs/server-module-interface';
+
+export class AuthMiddleware implements IMiddlewareService {
+  getMiddlewares() {
+    return [{
+      middlewareId: 'auth',
+      handler: async (params, ctx, next) => {
+        // 认证逻辑...
+        await next();
+      }
+    }];
+  }
+}
+
+export const authMiddlewareDef: IMiddlewareServiceDef = {
+  serviceTag: 'authMiddleware',
+  serviceImpl: AuthMiddleware,
+  meta: { usageType: 'middleware' }
+};
+```
+
+### 模块入口文件
+
+**`src/server/server-module.ts`**
+
+```typescript
+import type { IModule } from '@linyjs/server-module-interface';
+import { articleControllerDef } from './controllers/article-controller.js';
+import { authMiddlewareDef } from './middleware/auth-middleware.js';
+
+export const myServerModule: IModule = {
+  name: 'myServer',
+  serviceDefs: [articleControllerDef, authMiddlewareDef]
+};
+```
+
+> 模块入口文件只负责**导入和组装**，不包含任何 ServiceDef 声明或服务实现类。
+
+---
+
+## 客户端模块同样适用
+
+以上两条规范同样适用于客户端模块：
+
+### ✅ 正确写法
+
+**`src/client/index.tsx`**
+
+```typescript
+import type { IModule, IRouteDef } from '@linyjs/client-module-interface';
+import React from 'react';
+
+function HelloPage() {
+  return <div>Hello!</div>;
+}
+
+class HelloRouteService implements IRouteService {
+  basePath = '/hello';
+
+  getRoutes() {
+    return [{
+      path: '/',
+      component: HelloPage,
+      key: 'hello-page',
+      meta: { title: 'Hello' }
+    }];
+  }
+}
+
+const helloRouteDef: IRouteDef = {
+  serviceTag: 'helloRoute',
+  serviceImpl: HelloRouteService,
+  meta: { usageType: 'route' }
+};
+
+export const helloClientModule: IModule = {
+  name: 'helloClient',
+  serviceDefs: [helloRouteDef]
+};
+```
+
+### ❌ 错误写法
+
+```typescript
+// ServiceDef 内联在数组中，且使用了匿名类
+export const helloClientModule: IModule = {
+  name: 'helloClient',
+  serviceDefs: [{
+    serviceTag: 'helloRoute',
+    serviceImpl: class {
+      basePath = '/hello';
+      getRoutes() { /* ... */ }
+    },
+    meta: { usageType: 'route' }
+  }]
+};
+```
+
+> 客户端模块中如果文件较小（如 Hello World 级别），可以将类、ServiceDef 和模块声明放在同一个文件中。但仍然禁止内联在 `serviceDefs` 数组中，也禁止使用匿名类作为 `serviceImpl`。
+
+---
+
+## 检查清单
+
+在提交代码前，请检查以下几点：
+
+- [ ] 所有 `ServiceDef` 都声明为独立变量，未内联在 `serviceDefs` 数组中
+- [ ] 每个 `ServiceDef` 声明都紧挨着对应的实现类，在同一个文件中
+- [ ] `serviceImpl` 使用具名类，不使用匿名类或内联箭头函数
+- [ ] 模块入口文件（`server-module.ts` / `client-module.ts`）只做导入和组装，不包含 ServiceDef 声明
+- [ ] 导入类型时包含 `IServiceDef`（或其子类型如 `IControllerServiceDef`），为声明提供类型标注
+
+## 相关文档
+
+- 📖 [服务端模块开发](../guides/server-module.md)
+- 📖 [客户端模块开发](../guides/client-module.md)
+- 📖 [命名规范](./naming-conventions.md)
+- ⚠️ [错误处理](./error-handling.md)
+
+---
+
+**上一篇**: [命名规范](./naming-conventions.md) | **下一篇**: [错误处理](./error-handling.md)

package/docs/faq.md

@@ -0,0 +1,322 @@
+# 常见问题 (FAQ)
+
+## 入门相关
+
+### Q1: linyjs 是什么?
+
+**A:** linyjs 是一个插件式的前后端应用平台,允许开发者通过创建 `.mpk` 格式的插件来扩展平台功能。它提供了完整的前后端开发框架,包括依赖注入、权限控制、UI扩展等特性。
+
+### Q2: 我需要哪些前置知识?
+
+**A:** 
+- TypeScript (必需)
+- React (客户端开发)
+- Node.js (服务端开发)
+- 基本的 HTTP/API 概念
+
+### Q3: 如何开始第一个插件?
+
+**A:** 阅读 [快速开始](./getting-started/quick-start.md) 教程,5分钟即可创建你的第一个插件!
+
+---
+
+## 安装和配置
+
+### Q4: 如何安装 linyjs CLI 工具?
+
+**A:** 
+```bash
+# 全局安装(推荐)
+npm install -g @linyjs/cli
+
+# 或使用 npx
+npx @linyjs/cli <command>
+```
+
+### Q5: TypeScript 编译错误怎么办?
+
+**A:** 确保:
+1. 安装了正确版本的 TypeScript (`^5.7.0`)
+2. `tsconfig.json` 配置正确
+3. 所有类型定义包已安装 (`@types/react` 等)
+
+### Q6: 如何更新到最新版本?
+
+**A:** 
+```bash
+npm update @linyjs/server-module-interface
+npm update @linyjs/client-module-interface
+npm update @linyjs/cli
+```
+
+---
+
+## 开发相关
+
+### Q7: 如何调试插件?
+
+**A:** 
+
+**方法 1: 使用 tsx 运行**
+```bash
+npx tsx src/server/index.ts
+```
+
+**方法 2: 添加日志**
+```typescript
+console.log('[MyPlugin]', 'Debug info:', data);
+```
+
+**方法 3: 浏览器 DevTools**
+客户端代码可以在浏览器中调试。
+
+### Q8: 插件之间如何通信?
+
+**A:** 
+
+**方式 1: 通过共享服务**
+```typescript
+// 插件 A 提供服务
+export const serviceA = {
+  serviceTag: 'sharedService',
+  serviceImpl: SharedService
+};
+
+// 插件 B 使用服务
+export const serviceB = {
+  serviceTag: 'consumer',
+  serviceImpl: ConsumerService,
+  dependencies: ['pluginA.sharedService']
+};
+```
+
+**方式 2: 通过全局状态**
+使用 jotai atoms 共享状态。
+
+### Q9: 如何处理插件版本兼容性?
+
+**A:** 在 `manifest.json` 中指定依赖版本:
+```json
+{
+  "dependencies": {
+    "core-auth": "^1.0.0",
+    "core-mongodb": ">=1.2.0"
+  }
+}
+```
+
+### Q10: 插件可以修改其他插件的行为吗?
+
+**A:** 可以通过以下方式:
+1. **覆盖路由**: 注册相同路径的路由(后加载的优先)
+2. **扩展 Slot**: 向现有 Slot 添加新组件
+
+---
+
+## 打包和发布
+
+### Q11: 如何打包插件?
+
+**A:** 使用 CLI 工具:
+```bash
+cd my-plugin
+npx @linyjs/cli pack
+```
+
+这将自动完成:构建、生成 manifest、验证结构、打包压缩。
+
+### Q12: .mpk 文件是什么格式?
+
+**A:** `.mpk` 是 ZIP 压缩格式,包含:
+```
+my-plugin.mpk (ZIP)
+├── manifest.json       # 插件清单
+├── server/             # 服务端模块
+│   └── index.js        # 编译后的 JS
+├── client/             # 客户端模块
+│   └── index.js        # 编译后的 JS
+└── assets/             # 静态资源
+```
+
+### Q13: 如何测试插件?
+
+**A:** 
+```bash
+# 将插件复制到 extensions 目录
+cp my-plugin.mpk /path/to/linyjs/packages/ssr/extensions/
+
+# 启动 SSR 服务器
+cd /path/to/linyjs/packages/ssr
+npx tsx src/demo/dev-server-with-pkg.tsx
+```
+
+---
+
+## 高级主题
+
+### Q14: 为什么我的插件无法访问 React Context?
+
+**A:** 这通常是因为 React 实例不共享导致的。确保:
+1. CLI 已 external React(默认行为)
+2. 宿主应用提供了 React(通过 Import Map)
+3. 所有插件使用同一个 React 版本
+
+```html
+<!-- 宿主应用的 HTML -->
+<script type="importmap">
+{
+  "imports": {
+    "react": "/vendor/react.production.min.js",
+    "react-dom": "/vendor/react-dom.production.min.js"
+  }
+}
+</script>
+```
+
+### Q15: CLI 打包的 Bundle 体积太大怎么办?
+
+**A:** CLI 默认启用了优化:
+- ✅ esbuild - 极速构建和小体积
+- ✅ Minification - 代码压缩
+- ✅ Tree Shaking - 移除未使用代码
+- ✅ External Dependencies - React 等由宿主提供
+
+进一步优化:
+```typescript
+// 使用懒加载
+const HeavyComponent = React.lazy(() => import('./HeavyComponent'))
+
+// 代码分割
+import('./module').then(module => {
+  // 动态导入
+})
+```
+
+### Q16: 如何处理插件卸载?
+
+**A:** 建议在插件中提供清理逻辑:
+```typescript
+export function onUninstall() {
+  // 清理数据
+  db.collection('my_data').deleteMany({ plugin: 'my-plugin' });
+}
+```
+
+### Q17: 插件可以访问环境变量吗?
+
+**A:** 可以,通过 `process.env`:
+```typescript
+const apiKey = process.env.MY_PLUGIN_API_KEY;
+```
+
+确保在 `.env` 文件中配置:
+```bash
+MY_PLUGIN_API_KEY=your-api-key
+```
+
+---
+
+## 性能和优化
+
+### Q18: 如何优化插件性能?
+
+**A:** 
+1. **懒加载组件**
+```typescript
+const HeavyComponent = React.lazy(() => import('./HeavyComponent'));
+```
+
+2. **避免不必要的重渲染**
+```typescript
+import { memo } from 'react';
+const ExpensiveComponent = memo(({ data }) => {
+  return <div>{/* ... */}</div>;
+});
+```
+
+3. **使用缓存**
+```typescript
+const cachedData = useMemo(() => expensiveCalculation(data), [data]);
+```
+
+### Q19: 如何减少 Bundle 大小?
+
+**A:** 
+- 使用 tree shaking(确保使用 ES modules)
+- External 大型依赖(如 lodash)
+- 代码分割和懒加载
+- 压缩图片等资源
+
+---
+
+## 安全性
+
+### Q20: 如何防止 XSS 攻击?
+
+**A:** 
+```typescript
+function SafeDisplay({ content }: { content: string }) {
+  // 转义 HTML
+  const escaped = escapeHtml(content);
+  return <div dangerouslySetInnerHTML={{ __html: escaped }} />;
+}
+```
+
+### Q21: 如何防止 SQL 注入?
+
+**A:** 使用参数化查询:
+```typescript
+// ❌ 不安全
+const user = await db.collection('users').findOne({ 
+  email: userInput  // 可能被注入
+});
+
+// ✅ 安全(使用 MongoDB 的参数化查询)
+const user = await db.collection('users').findOne({ 
+  email: userInput  // MongoDB 会自动处理
+});
+```
+
+### Q22: 如何验证用户输入?
+
+**A:** 
+```typescript
+handler: async (params) => {
+  const { email } = params.body;
+  
+  // 验证邮箱格式
+  if (!isValidEmail(email)) {
+    return {
+      status: 400,
+      data: { error: 'Invalid email format' }
+    };
+  }
+}
+```
+
+---
+
+## 获取帮助
+
+### Q23: 遇到问题怎么办?
+
+**A:** 
+1. 📖 查阅本文档和相关指南
+2. 💡 查看[示例项目](../examples/)
+3. 🔍 搜索 GitHub Issues
+4. 💬 在社区论坛提问
+5. 🐛 报告 Bug: [GitHub Issues](https://github.com/linyjs/linyjs/issues)
+
+### Q24: 如何贡献文档?
+
+**A:** 
+1. Fork 仓库
+2. 修改或添加文档
+3. 提交 Pull Request
+4. 等待审查和合并
+
+详见 [CONTRIBUTING.md](../CONTRIBUTING.md)
+
+---
+
+**返回**: [文档首页](../README.md)