@linyjs/plugin-docs 0.0.13

package/examples/hello-world/README.md

@@ -0,0 +1,101 @@
+# Hello World Example Plugin
+
+最简单的 linyjs 插件示例,展示基本的 API 和页面开发。
+
+## 📋 功能
+
+- ✅ 服务端: `/api/hello` API 端点
+- ✅ 客户端: `/hello` 页面,可输入名字并显示问候语
+- ✅ 交互式 UI: 实时更新问候消息
+
+## 🚀 快速开始
+
+### 1. 安装依赖
+
+```bash
+npm install
+```
+
+### 2. 开发模式
+
+```bash
+npm run dev
+```
+
+这会在文件更改时自动重新编译。
+
+### 3. 构建插件
+
+```bash
+npm run build
+```
+
+编译后的文件将输出到 `dist/` 目录。
+
+### 4. 打包为 .mpk
+
+```bash
+npx @linyjs/cli pack
+```
+
+生成 `hello-world-example.mpk` 文件。
+
+### 5. 测试插件
+
+```bash
+# 复制插件到 extensions 目录
+cp hello-world-example.mpk /path/to/linyjs/packages/ssr/extensions/
+
+# 启动 SSR 服务器
+cd /path/to/linyjs/packages/ssr
+npx tsx src/demo/dev-server-with-pkg.tsx
+```
+
+访问 `http://localhost:3000/hello` 查看效果!
+
+## 📁 项目结构
+
+```
+hello-world/
+├── package.json          # NPM 配置
+├── tsconfig.json         # TypeScript 配置
+└── src/
+    ├── server/
+    │   └── index.ts      # 服务端代码 (API)
+    └── client/
+        └── index.tsx     # 客户端代码 (React 页面)
+```
+
+## 💡 代码说明
+
+### 服务端 (`src/server/index.ts`)
+
+定义了一个简单的 GET API:
+
+```typescript
+{
+  method: 'GET',
+  path: '/api/hello',
+  handler: async (params, ctx) => {
+    return { message: `Hello, ${name}!` };
+  }
+}
+```
+
+### 客户端 (`src/client/index.tsx`)
+
+创建了一个 React 页面组件:
+
+- 使用 `useState` 管理状态
+- 使用 `useEffect` 调用 API
+- 提供输入框让用户输入名字
+
+## 🔗 相关文档
+
+- [Plugin Development Guide](node_modules/@linyjs/plugin-docs/docs/getting-started/quick-start.md)
+- [Server Module Guide](node_modules/@linyjs/plugin-docs/docs/guides/server-module.md)
+- [Client Module Guide](node_modules/@linyjs/plugin-docs/docs/guides/client-module.md)
+
+## 📝 许可证
+
+MIT

package/examples/hello-world/dist/client/index.d.ts

@@ -0,0 +1,5 @@
+import type { IModule } from '@linyjs/client-module-interface';
+/**
+ * 客户端模块定义
+ */
+export declare const helloClientModule: IModule;

package/examples/hello-world/dist/client/index.js

@@ -0,0 +1,80 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import React from 'react';
+/**
+ * Hello World 页面组件
+ */
+function HelloPage() {
+    const [message, setMessage] = React.useState('Loading...');
+    const [name, setName] = React.useState('World');
+    // 调用 API 获取问候消息
+    React.useEffect(() => {
+        fetch(`/api/hello?name=${encodeURIComponent(name)}`)
+            .then(res => res.json())
+            .then(data => {
+            setMessage(data.message);
+        })
+            .catch(err => {
+            console.error('Failed to fetch:', err);
+            setMessage('Error loading message');
+        });
+    }, [name]);
+    return (_jsxs("div", { style: {
+            padding: '40px',
+            maxWidth: '600px',
+            margin: '0 auto',
+            fontFamily: 'Arial, sans-serif'
+        }, children: [_jsx("h1", { style: { color: '#333' }, children: "\uD83D\uDC4B Hello World Plugin" }), _jsx("div", { style: {
+                    marginTop: '20px',
+                    padding: '20px',
+                    backgroundColor: '#f5f5f5',
+                    borderRadius: '8px'
+                }, children: _jsx("p", { style: { fontSize: '18px', color: '#666' }, children: message }) }), _jsxs("div", { style: { marginTop: '20px' }, children: [_jsx("label", { style: { display: 'block', marginBottom: '8px', color: '#666' }, children: "Enter your name:" }), _jsx("input", { type: "text", value: name, onChange: (e) => setName(e.target.value), placeholder: "Enter your name", style: {
+                            padding: '10px',
+                            fontSize: '16px',
+                            border: '1px solid #ddd',
+                            borderRadius: '4px',
+                            width: '100%',
+                            boxSizing: 'border-box'
+                        } })] }), _jsxs("div", { style: {
+                    marginTop: '30px',
+                    padding: '15px',
+                    backgroundColor: '#e3f2fd',
+                    borderRadius: '4px',
+                    fontSize: '14px',
+                    color: '#1976d2'
+                }, children: [_jsx("strong", { children: "\uD83D\uDCA1 Tip:" }), " This is a minimal linyjs plugin example. Try modifying the code in ", _jsx("code", { children: "src/server/index.ts" }), " and ", _jsx("code", { children: "src/client/index.tsx" }), "."] })] }));
+}
+/**
+ * 路由服务
+ */
+class HelloRouteService {
+    constructor() {
+        this.basePath = '/hello';
+    }
+    getRoutes() {
+        return [
+            {
+                path: '/',
+                component: HelloPage,
+                key: 'hello-page',
+                meta: {
+                    title: 'Hello World',
+                    requiresAuth: false
+                }
+            }
+        ];
+    }
+}
+/**
+ * 客户端模块定义
+ */
+export const helloClientModule = {
+    name: 'helloClient',
+    serviceDefs: [
+        {
+            serviceTag: 'helloRoute',
+            serviceImpl: HelloRouteService,
+            meta: { usageType: 'route' }
+        }
+    ]
+};

package/examples/hello-world/dist/server/index.d.ts

@@ -0,0 +1,5 @@
+import type { IModule } from '@linyjs/server-module-interface';
+/**
+ * 服务端模块定义
+ */
+export declare const helloServerModule: IModule;

package/examples/hello-world/dist/server/index.js

@@ -0,0 +1,38 @@
+/**
+ * Hello World 控制器
+ * 提供一个简单的 API 端点返回问候消息
+ */
+class HelloController {
+    getRoutes() {
+        return [
+            {
+                method: 'GET',
+                path: '/api/hello',
+                middlewares: [],
+                responseType: 'json',
+                handler: async (params, ctx) => {
+                    // 获取查询参数(如果有)
+                    const name = params.query?.name || 'World';
+                    return {
+                        message: `Hello, ${name}!`,
+                        timestamp: new Date().toISOString(),
+                        plugin: 'hello-world-example'
+                    };
+                }
+            }
+        ];
+    }
+}
+/**
+ * 服务端模块定义
+ */
+export const helloServerModule = {
+    name: 'helloServer',
+    serviceDefs: [
+        {
+            serviceTag: 'helloController',
+            serviceImpl: HelloController,
+            meta: { usageType: 'controller' }
+        }
+    ]
+};

package/examples/hello-world/node_modules/.package-lock.json

@@ -0,0 +1,61 @@
+{
+  "name": "@linyjs/example-hello-world",
+  "version": "1.0.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "node_modules/@linyjs/client-module-interface": {
+      "version": "0.0.1",
+      "resolved": "https://registry.npmmirror.com/@linyjs/client-module-interface/-/client-module-interface-0.0.1.tgz",
+      "integrity": "sha512-StKnCtzKq+ZHoApWQqOHEPrlMq0VqZ5C4ZYB9t27LNOzep8j4qwMqNnEP99S/KC4m/9rVGJlnJw0O+Kf2NVYYg==",
+      "peerDependencies": {
+        "react": "^19.0.0"
+      }
+    },
+    "node_modules/@linyjs/server-module-interface": {
+      "version": "0.0.1",
+      "resolved": "https://registry.npmmirror.com/@linyjs/server-module-interface/-/server-module-interface-0.0.1.tgz",
+      "integrity": "sha512-jrwW0uI8F7TCwGMvGVW4EkxcdDaXTIZhDS5tcahTiA9pqsNDMXULcy0oPrmaPMp6uaqdt3rSTp0ybThggym/RQ=="
+    },
+    "node_modules/@types/react": {
+      "version": "19.2.17",
+      "resolved": "https://registry.npmmirror.com/@types/react/-/react-19.2.17.tgz",
+      "integrity": "sha512-MXfmqaVPEVgkBT/aY0aGCkRWWtByiYQXo3xdQ8r5RzuFrPiRn8Gar2tQdXSUQ2GKV3bkXckek89V8wQBY2Q/Aw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "csstype": "^3.2.2"
+      }
+    },
+    "node_modules/csstype": {
+      "version": "3.2.3",
+      "resolved": "https://registry.npmmirror.com/csstype/-/csstype-3.2.3.tgz",
+      "integrity": "sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/react": {
+      "version": "19.2.7",
+      "resolved": "https://registry.npmmirror.com/react/-/react-19.2.7.tgz",
+      "integrity": "sha512-HNe9WslTbXmFK8o8cmwgAeJFSBvt1bPdHCVKtaaV+WlAN36mpT4hcRpwbf3fY56ar2oIXzsBpOAiIRHAdY0OlQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/typescript": {
+      "version": "5.9.3",
+      "resolved": "https://registry.npmmirror.com/typescript/-/typescript-5.9.3.tgz",
+      "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "tsc": "bin/tsc",
+        "tsserver": "bin/tsserver"
+      },
+      "engines": {
+        "node": ">=14.17"
+      }
+    }
+  }
+}

package/examples/hello-world/node_modules/@linyjs/client-module-interface/HOOKS_USAGE.md

@@ -0,0 +1,281 @@
+# 资源消费 Hooks 使用指南
+
+本文档展示如何在模块中使用 `useClientComponent`、`useClientHook` 和 `useClientService`。
+
+## 快速开始
+
+### 1. 导入 Hooks
+
+```typescript
+import { 
+  useClientComponent, 
+  useClientHook, 
+  useClientService 
+} from '@ling/client-module-interface'
+```
+
+### 2. 基本用法
+
+#### 使用组件
+
+```typescript
+function MyPage() {
+  // 跨模块引用组件
+  const Avatar = useClientComponent('userModule.userComponents.Avatar')
+  
+  return (
+    <div>
+      {Avatar && <Avatar userId="123" size="large" />}
+    </div>
+  )
+}
+```
+
+#### 使用 Hook
+
+```typescript
+function AuthStatus() {
+  // 定义 Hook 类型
+  type UseAuthHook = () => { 
+    isAuthenticated: boolean
+    user: { id: string; name: string } | null 
+  }
+  
+  // 引用 Hook
+  const useAuth = useClientHook<UseAuthHook>('authModule.authHooks.useAuth')
+  
+  // 调用 Hook
+  const authState = useAuth ? useAuth() : null
+  
+  return (
+    <div>
+      {authState?.isAuthenticated ? '已登录' : '未登录'}
+    </div>
+  )
+}
+```
+
+#### 使用服务
+
+```typescript
+interface IUserService {
+  getUser(id: string): Promise<User>
+  updateUser(id: string, data: Partial<User>): Promise<void>
+}
+
+function UserManagement() {
+  // 引用服务
+  const userService = useClientService<IUserService>('userModule.userService')
+  
+  const handleLoadUser = async () => {
+    if (userService) {
+      const user = await userService.getUser('123')
+      console.log(user)
+    }
+  }
+  
+  return <button onClick={handleLoadUser}>加载用户</button>
+}
+```
+
+## 高级用法
+
+### 1. 混合使用多种资源
+
+```typescript
+function UserProfile() {
+  // 引用多个组件
+  const Avatar = useClientComponent('userModule.userComponents.Avatar')
+  const Card = useClientComponent('uiModule.uiComponents.Card')
+  const Button = useClientComponent('uiModule.uiComponents.Button')
+  
+  // 引用 Hook
+  type UseAuthHook = () => { isAuthenticated: boolean; user: any }
+  const useAuth = useClientHook<UseAuthHook>('authModule.authHooks.useAuth')
+  const authState = useAuth ? useAuth() : null
+  
+  // 引用服务
+  const userService = useClientService<IUserService>('userModule.userService')
+  
+  const handleUpdate = async () => {
+    if (userService && authState?.user) {
+      await userService.updateUser(authState.user.id, { name: 'New Name' })
+    }
+  }
+  
+  return (
+    <div>
+      {Card && (
+        <Card title="用户信息">
+          {Avatar && authState?.user && (
+            <Avatar userId={authState.user.id} />
+          )}
+          
+          <p>{authState?.user?.name}</p>
+          
+          {Button && (
+            <Button text="更新" onClick={handleUpdate} />
+          )}
+        </Card>
+      )}
+    </div>
+  )
+}
+```
+
+### 2. 条件渲染
+
+```typescript
+function ConditionalExample() {
+  const Avatar = useClientComponent('userModule.userComponents.Avatar')
+  
+  // 如果组件不存在，显示降级 UI
+  if (!Avatar) {
+    return <div>头像组件加载中...</div>
+  }
+  
+  return <Avatar userId="123" />
+}
+```
+
+### 3. 错误处理
+
+```typescript
+function ErrorHandlingExample() {
+  const userService = useClientService<IUserService>('userModule.userService')
+  
+  const handleAction = async () => {
+    if (!userService) {
+      console.error('用户服务未找到')
+      return
+    }
+    
+    try {
+      const user = await userService.getUser('123')
+      console.log('用户加载成功:', user)
+    } catch (error) {
+      console.error('加载用户失败:', error)
+    }
+  }
+  
+  return <button onClick={handleAction}>加载用户</button>
+}
+```
+
+## 最佳实践
+
+### ✅ 推荐做法
+
+1. **使用泛型提供类型约束**
+   ```typescript
+   const userService = useClientService<IUserService>('...')
+   const useAuth = useClientHook<UseAuthHook>('...')
+   ```
+
+2. **进行空值检查**
+   ```typescript
+   const Avatar = useClientComponent('...')
+   if (Avatar) {
+     return <Avatar />
+   }
+   ```
+
+3. **使用完整的 RegistryKey**
+   ```typescript
+   // ✅ 推荐：完整路径
+   useClientComponent('userModule.userComponents.Avatar')
+   
+   // ⚠️ 当前版本也需要完整路径（未来会支持短路径）
+   useClientComponent('userComponents.Avatar')
+   ```
+
+4. **提取类型定义**
+   ```typescript
+   // 在单独的文件中定义类型
+   type UseAuthHook = () => { isAuthenticated: boolean; user: any }
+   
+   // 在使用时引用
+   const useAuth = useClientHook<UseAuthHook>('...')
+   ```
+
+### ❌ 避免的做法
+
+1. **不要忽略空值检查**
+   ```typescript
+   // ❌ 危险：可能运行时错误
+   const Avatar = useClientComponent('...')
+   return <Avatar />  // Avatar 可能是 undefined
+   
+   // ✅ 安全
+   const Avatar = useClientComponent('...')
+   return Avatar ? <Avatar /> : null
+   ```
+
+2. **不要硬编码魔法字符串**
+   ```typescript
+   // ❌ 不推荐
+   const Avatar = useClientComponent('userModule.userComponents.Avatar')
+   
+   // ✅ 推荐：使用常量
+   const AVATAR_COMPONENT = 'userModule.userComponents.Avatar'
+   const Avatar = useClientComponent(AVATAR_COMPONENT)
+   ```
+
+3. **不要在循环中调用 Hook**
+   ```typescript
+   // ❌ 违反 React Hooks 规则
+   componentNames.forEach(name => {
+     const Component = useClientComponent(name)  // 错误！
+   })
+   
+   // ✅ 正确：在顶层调用
+   const Component1 = useClientComponent('module.service.Component1')
+   const Component2 = useClientComponent('module.service.Component2')
+   ```
+
+## 常见问题
+
+### Q: 为什么返回的是 `undefined`？
+
+A: 可能的原因：
+1. 资源未注册（检查模块是否正确加载）
+2. RegistryKey 拼写错误
+3. 模块尚未加载完成
+
+解决方法：
+- 检查控制台警告信息
+- 确认模块已正确声明和加载
+- 验证 RegistryKey 格式是否正确
+
+### Q: 如何实现模块内引用（省略 moduleName）？
+
+A: 当前版本需要显式传递完整路径。未来会通过 `ModuleContext` 自动获取当前模块名，届时可以这样使用：
+
+```typescript
+// 未来版本（TODO）
+const Avatar = useClientComponent('userComponents.Avatar')  // 自动补全为 'currentModule.userComponents.Avatar'
+```
+
+### Q: 如何调试资源查找问题？
+
+A: Hook 会在找不到资源时输出警告信息：
+
+```
+[useClientComponent] Component not found: "userModule.userComponents.Avatar"
+```
+
+检查：
+1. 模块是否正确加载
+2. 服务是否正确注册
+3. RegistryKey 是否匹配
+
+## 完整示例
+
+查看以下文件了解完整的使用示例：
+- `src/hooks-example.tsx` - 详细的使用示例
+- `../../packages/ssr/src/demo/client-modules.tsx` - SSR 演示项目中的实际应用
+
+## 相关文档
+
+- [前端模块接口设计](../../spec/前端模块接口设计.md)
+- [前端插件式架构设计](../../spec/前端插件式架构设计.md)