@linyjs/plugin-docs 0.0.13

package/docs/migration/v0-to-v1.md

@@ -0,0 +1,354 @@
+# v0.x 到 v1.0 迁移指南
+
+本指南将帮助你将 Linyjs 相关插件从 v0.x 版本迁移到 v1.0 版本。
+
+## 概述
+
+v1.0 版本是 Linyjs 框架的一个重要里程碑，包含了多个重大改进和API调整。本指南将详细说明这些变化以及如何进行迁移。
+
+## ⚠️ 重大变更
+
+### 1. 插件接口更新
+
+#### 旧版本
+```typescript
+import { IPlugin } from '@linyjs/server-module-interface';
+
+export const myPlugin: IPlugin = {
+  // ...
+};
+```
+
+#### 新版本  
+```typescript
+import type { IModule } from '@linyjs/server-module-interface';
+
+export const myPlugin: IModule = {
+  name: 'myPlugin',
+  serviceDefs: [
+    // ...
+  ]
+};
+```
+
+### 2. 接口名称变更
+
+- `IPlugin` 接口重命名为 `IModule`
+- `@linyjs/plugin-interface` 包已重命名为 `@linyjs/server-module-interface`
+- 客户端接口移至 `@linyjs/client-module-interface`
+
+### 3. 生命周期方法变更
+
+#### 旧版本
+```typescript
+class MyService {
+  onStart() {
+    // 启动逻辑
+  }
+
+  onStop() {
+    // 销毁逻辑
+  }
+}
+```
+
+#### 新版本
+```typescript
+class MyService {
+  onModuleInit() {
+    // 启动逻辑
+  }
+
+  onModuleDestroy() {
+    // 销毁逻辑
+  }
+}
+```
+
+## 🚚 迁移步骤
+
+### 步骤 1: 更新 package.json 依赖
+
+```diff
+{
+  "dependencies": {
+-   "@linyjs/plugin-interface": "^0.7.0",
++   "@linyjs/server-module-interface": "^1.0.0",
++   "@linyjs/client-module-interface": "^1.0.0",
++   "@linyjs/ui-slots-interface": "^1.0.0",
+    "@linyjs/core": "^1.0.0"
+  },
+  "devDependencies": {
+-   "@linyjs/plugin-interface": "^0.7.0"
++   "@linyjs/server-module-interface": "^1.0.0"
+  }
+}
+```
+
+### 步骤 2: 更新导入语句
+
+```diff
+- import { IPlugin } from '@linyjs/plugin-interface';
++ import type { IModule } from '@linyjs/server-module-interface';
+  
+- export const myPlugin: IPlugin = {
++ export const myPlugin: IModule = {
++   name: 'myPlugin',
++   serviceDefs: [
++     {
++       serviceTag: 'myService',
++       serviceImpl: MyService,
++       meta: { usageType: 'service' }
++     }
++   ]
+  };
+```
+
+### 步骤 3: 更新服务类定义
+
+```diff
+class MyService {
+- onStart() {
++ onModuleInit() {
+    // 启动逻辑
+  }
+
+- onStop() {
++ onModuleDestroy() {
+    // 销毁逻辑
+  }
+}
+```
+
+### 步骤 4: 更新模块配置
+
+如果使用配置元数据，更新其格式：
+
+```typescript
+{
+  serviceTag: 'myService',
+  serviceImpl: MyService,
+  meta: {
+    usageType: 'controller', // 或 'service', 'component'
+    lifecycle: {
+      init: 'onModuleInit',
+      destroy: 'onModuleDestroy'
+    }
+  }
+}
+```
+
+## 🧩 特定模块迁移
+
+### 认证和授权模块
+
+#### 旧版本
+```typescript
+import { AuthMiddleware } from '@linyjs/auth';
+```
+
+#### 新版本
+```typescript
+import { AuthController } from '@linyjs/auth';
+// 中间件现在通过控制器注册
+```
+
+### 权限控制模块
+
+#### 旧版本
+```typescript
+checkPermission(user, 'read', 'article');
+```
+
+#### 新版本
+```typescript
+checkPermission({
+  userId: user.id,
+  action: 'read',
+  resource: 'article'
+});
+```
+
+### MongoDB 集成模块
+
+#### 旧版本
+```typescript
+import { MongoConnector } from '@linyjs/mdb';
+```
+
+#### 新版本
+```typescript
+import { MongoService } from '@linyjs/mdb';
+```
+
+## 🖥️ 前端迁移
+
+### 客户端模块定义
+
+```diff
+- import { IPlugin } from '@linyjs/plugin-interface';
++ import type { IModule } from '@linyjs/client-module-interface';
+
+- export const myPlugin: IPlugin = {
++ export const myPlugin: IModule = {
++   name: 'myPlugin',
++   serviceDefs: [
++     {
++       serviceTag: 'myRoute',
++       serviceImpl: MyRouteService,
++       meta: { usageType: 'route' }
++     }
++   ]
+  };
+```
+
+### UI 插槽API
+
+#### 旧版本
+```typescript
+slots.register('sidebar', MyComponent);
+```
+
+#### 新版本
+```typescript
+UI.registerSlot({
+  name: 'sidebar',
+  component: MyComponent,
+  priority: 100
+});
+```
+
+## 🎯 路由系统变更
+
+### 路径参数语法
+
+#### 旧版本
+```typescript
+{
+  path: '/user/:id(\d+)',
+  component: UserDetail
+}
+```
+
+#### 新版本
+```typescript
+{
+  path: '/user/:id',
+  component: UserDetail,
+  params: {
+    id: { pattern: '\\d+', required: true }
+  }
+}
+```
+
+## 📦 构建工具更新
+
+### webpack 配置
+
+如果自定义了 webpack 配置，可能需要更新：
+
+```diff
+module.exports = {
+  resolve: {
+    alias: {
+-     '@linyjs/interface': '@linyjs/server-module-interface',
+-     '@linyjs/client': '@linyjs/client-module-interface'
++     // 不再需要这些别名，使用新包名即可
+    }
+  }
+};
+```
+
+### TypeScript 配置
+
+```diff
+{
+  "compilerOptions": {
+    "paths": {
+-     "@linyjs/*": ["packages/*/src"]
++     "@linyjs/*": ["packages/*/src"],
++     "@linyjs/server-module-interface": ["packages/server-module-interface/src"],
++     "@linyjs/client-module-interface": ["packages/client-module-interface/src"]
+    }
+  }
+}
+```
+
+## 🧪 测试代码迁移
+
+### 单元测试
+
+```diff
+- import { createPlugin } from '@linyjs/testing';
++ import { createModule } from '@linyjs/testing';
+
+- const plugin = createPlugin(MyPlugin);
++ const module = createModule(MyPlugin);
+```
+
+## 🔧 工具命令变更
+
+### CLI 命令更新
+
+#### 旧版本
+```bash
+linyjs plugin:generate my-plugin
+linyjs docs:open
+linyjs example:create
+```
+
+#### 新版本
+```bash
+# 新的 CLI 集成方式
+linyjs docs          # 访问文档
+linyjs example <name>  # 生成示例
+linyjs docs --open   # 在浏览器中打开
+```
+
+## 📖 新特性
+
+完成迁移后，你将可以使用以下新功能：
+
+1. **TypeScript 5.0+ 全面支持** - 更强的类型推断
+2. **ESM 默认支持** - 原生模块支持
+3. **插件热重载** - 开发时的快速迭代
+4. **自动 API 生成** - 基于代码生成 OpenAPI 规范
+5. **更好的错误处理** - 详细的错误信息和建议
+6. **性能优化** - 更快的启动和构建速度
+
+## ❓ 常见问题
+
+### Q: 我的插件使用了反射 API，需要更新吗？
+
+A: 是的。v1.0 使用了新的元数据格式，建议检查相关代码。
+
+### Q: 如何测试迁移是否成功？
+
+A: 运行以下命令：
+```bash
+npm run type-check    # TypeScript 检查
+npm run build         # 构建检查
+npm test              # 运行测试
+```
+
+### Q: 我还能使用 v0.x 版本的依赖吗？
+
+A: 不建议。v1.0 有一些不兼容的API变更，建议使用新版本的依赖。
+
+## 📚 更多资源
+
+- [插件开发文档](../getting-started/quick-start.md)
+- [API 参考](../api-reference/index.md)
+- [示例项目](../../examples/hello-world/)
+- [GitHub Discussions](https://github.com/your-repo/linyjs/discussions)
+
+## 🆘 需要帮助？
+
+如果在迁移过程中遇到问题，请：
+
+1. 查看详细的错误信息
+2. 查阅相关模块的文档  
+3. 在 [GitHub Discussions](https://github.com/your-repo/linyjs/discussions) 中提问
+4. 创建 [GitHub Issue](https://github.com/your-repo/linyjs/issues) 报告问题
+
+我们在这里为你提供帮助！