@linyjs/plugin-docs 0.1.2 → 0.1.4

package/docs/guides/authentication.md

@@ -0,0 +1,428 @@
+# 用户认证
+
+本指南介绍如何在 linyjs 插件中使用认证系统实现用户登录、注册和权限验证。
+
+## 概述
+
+linyjs 提供完整的用户认证系统，支持:
+
+- 🔐 用户注册和登录
+- 🪙 JWT Token 认证
+- 🛡️ 路由级别的认证保护
+- 👤 用户信息管理
+
+## 配置认证服务
+
+### 在服务端模块中注入依赖
+
+```typescript
+import type { IModule, IServiceDef } from '@linyjs/server-module-interface';
+import { login, register, verifyToken } from '@linyjs/auth';
+
+class AuthController {
+  // ... 控制器实现
+}
+
+const authControllerDef: IServiceDef = {
+  serviceTag: 'authController',
+  serviceImpl: AuthController,
+  dependencies: [],
+  meta: { usageType: 'controller' }
+};
+
+export const myServerModule: IModule = {
+  name: 'myServer',
+  moduleDependencies: ['auth'],
+  serviceDefs: [authControllerDef]
+};
+```
+
+## 基本认证操作
+
+### 用户注册
+
+```typescript
+import { register } from '@linyjs/auth';
+
+class AuthController {
+  getRoutes() {
+    return [{
+      method: 'POST' as const,
+      path: '/api/auth/register',
+      middlewares: [],
+      responseType: 'json' as const,
+      handler: async (req: any) => {
+        const { username, email, password } = req.body;
+        
+        try {
+          const result = await register(username, email, password);
+          return {
+            success: true,
+            message: 'Registration successful',
+            data: result
+          };
+        } catch (error) {
+          return {
+            success: false,
+            message: error instanceof Error ? error.message : 'Registration failed'
+          };
+        }
+      }
+    }];
+  }
+}
+```
+
+### 用户登录
+
+```typescript
+import { login } from '@linyjs/auth';
+
+class AuthController {
+  getRoutes() {
+    return [{
+      method: 'POST' as const,
+      path: '/api/auth/login',
+      middlewares: [],
+      responseType: 'json' as const,
+      handler: async (req: any) => {
+        const { identifier, password } = req.body;
+        
+        try {
+          const result = await login(identifier, password);
+          return {
+            success: true,
+            message: 'Login successful',
+            data: result
+          };
+        } catch (error) {
+          return {
+            success: false,
+            message: error instanceof Error ? error.message : 'Login failed'
+          };
+        }
+      }
+    }];
+  }
+}
+```
+
+### Token 验证
+
+```typescript
+import { verifyToken, getUserById } from '@linyjs/auth';
+
+class AuthController {
+  getRoutes() {
+    return [{
+      method: 'GET' as const,
+      path: '/api/auth/me',
+      middlewares: [],
+      responseType: 'json' as const,
+      handler: async (req: any) => {
+        const token = req.headers.authorization?.replace('Bearer ', '');
+        
+        if (!token) {
+          return {
+            success: false,
+            message: 'No token provided'
+          };
+        }
+        
+        try {
+          const payload = await verifyToken(token);
+          const user = await getUserById(payload.userId);
+          
+          return {
+            success: true,
+            data: user
+          };
+        } catch (error) {
+          return {
+            success: false,
+            message: 'Invalid token'
+          };
+        }
+      }
+    }];
+  }
+}
+```
+
+## 认证中间件
+
+### 创建认证中间件
+
+```typescript
+import { verifyToken, getUserById } from '@linyjs/auth';
+
+async function authMiddleware(req: any, res: any, next: any) {
+  const token = req.headers.authorization?.replace('Bearer ', '');
+  
+  if (!token) {
+    return res.status(401).json({
+      success: false,
+      message: 'Authentication token required'
+    });
+  }
+  
+  try {
+    const payload = await verifyToken(token);
+    const user = await getUserById(payload.userId);
+    
+    if (!user) {
+      return res.status(401).json({
+        success: false,
+        message: 'User not found'
+      });
+    }
+    
+    // 将用户信息添加到请求对象
+    req.user = user;
+    req.userId = user._id;
+    
+    next();
+  } catch (error) {
+    return res.status(401).json({
+      success: false,
+      message: 'Invalid authentication token'
+    });
+  }
+}
+```
+
+### 使用认证中间件
+
+```typescript
+class ProtectedController {
+  getRoutes() {
+    return [{
+      method: 'GET' as const,
+      path: '/api/protected',
+      middlewares: [authMiddleware],  // 使用认证中间件
+      responseType: 'json' as const,
+      handler: async (req: any) => {
+        return {
+          success: true,
+          message: `Hello ${req.user.username}! You have access to this protected route.`
+        };
+      }
+    }];
+  }
+}
+```
+
+## 客户端认证
+
+### 登录表单示例
+
+```typescript
+import type { IModule } from '@linyjs/client-module-interface';
+import React, { useState } from 'react';
+
+function LoginForm() {
+  const [formData, setFormData] = useState({
+    identifier: '',
+    password: ''
+  });
+  const [error, setError] = useState('');
+  
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    
+    try {
+      const response = await fetch('/api/auth/login', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json'
+        },
+        body: JSON.stringify(formData)
+      });
+      
+      const result = await response.json();
+      
+      if (result.success) {
+        // 保存 token 到 localStorage 或 cookie
+        localStorage.setItem('token', result.data.token);
+        // 跳转或刷新页面
+        window.location.reload();
+      } else {
+        setError(result.message);
+      }
+    } catch (err) {
+      setError('Network error');
+    }
+  };
+  
+  return (
+    <form onSubmit={handleSubmit}>
+      <div>
+        <label>用户名或邮箱:</label>
+        <input
+          type="text"
+          value={formData.identifier}
+          onChange={(e) => setFormData({ ...formData, identifier: e.target.value })}
+          required
+        />
+      </div>
+      <div>
+        <label>密码:</label>
+        <input
+          type="password"
+          value={formData.password}
+          onChange={(e) => setFormData({ ...formData, password: e.target.value })}
+          required
+        />
+      </div>
+      {error && <div className="error">{error}</div>}
+      <button type="submit">登录</button>
+    </form>
+  );
+}
+
+class LoginFormService {
+  getComponents() {
+    return {
+      LoginForm: {
+        component: LoginForm,
+        meta: { usageType: 'normal_component' }
+      }
+    };
+  }
+}
+
+const loginFormDef: IServiceDef = {
+  serviceTag: 'loginForm',
+  serviceImpl: LoginFormService,
+  meta: { usageType: 'normal_service' }
+};
+
+export const authClientModule: IModule = {
+  name: 'authClient',
+  serviceDefs: [loginFormDef]
+};
+```
+
+## 认证状态管理
+
+### 创建认证 Hook
+
+```typescript
+import { useState, useEffect } from 'react';
+
+interface User {
+  _id: string;
+  username: string;
+  email: string;
+  createdAt: Date;
+  roles?: string[];
+}
+
+export function useAuth() {
+  const [user, setUser] = useState<User | null>(null);
+  const [loading, setLoading] = useState(true);
+  
+  useEffect(() => {
+    const token = localStorage.getItem('token');
+    
+    if (!token) {
+      setLoading(false);
+      return;
+    }
+    
+    fetch('/api/auth/me', {
+      headers: {
+        'Authorization': `Bearer ${token}`
+      }
+    })
+    .then(response => response.json())
+    .then(result => {
+      if (result.success) {
+        setUser(result.data);
+      } else {
+        localStorage.removeItem('token');
+      }
+    })
+    .finally(() => {
+      setLoading(false);
+    });
+  }, []);
+  
+  const login = async (identifier: string, password: string) => {
+    const response = await fetch('/api/auth/login', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify({ identifier, password })
+    });
+    
+    const result = await response.json();
+    
+    if (result.success) {
+      localStorage.setItem('token', result.data.token);
+      setUser(result.data.user);
+      return true;
+    }
+    
+    return false;
+  };
+  
+  const logout = () => {
+    localStorage.removeItem('token');
+    setUser(null);
+  };
+  
+  const isAuthenticated = !!user;
+  
+  return {
+    user,
+    loading,
+    isAuthenticated,
+    login,
+    logout
+  };
+}
+```
+
+## 最佳实践
+
+### 1. Token 存储
+- 使用 `localStorage` 或 `cookie` 存储 token
+- 考虑安全性时优先使用 `httpOnly` cookie
+- 实现 token 自动刷新机制
+
+### 2. 错误处理
+- 捕获并处理认证相关的错误
+- 提供用户友好的错误消息
+- 记录详细的错误日志用于调试
+
+### 3. 安全性
+- 始终在服务端验证 token
+- 不要在客户端存储敏感信息
+- 使用强密码策略
+- 考虑实现两步验证增强安全性
+
+### 4. 用户体验
+- 记住用户的登录状态
+- 自动续期 token 避免频繁登录
+- 在 token 过期时友好提示用户
+
+## 故障排除
+
+### 常见问题
+
+1. **Token 无法验证**
+   - 检查 JWT_SECRET 是否正确配置
+   - 确认 token 未过期
+   - 验证 token 格式是否正确
+
+2. **用户无法登录**
+   - 检查用户名/邮箱和密码是否正确
+   - 确认用户账户已激活
+   - 检查数据库连接是否正常
+
+3. **中间件无法获取用户信息** 
+   - 确认 token 在请求头中正确传递
+   - 检查 verifyToken 函数是否正常工作
+   - 验证 getUserById 是否能找到对应用户

package/docs/guides/client-module.md

@@ -545,6 +545,12 @@ function MyPage() {
 
 ## 最佳实践
 
+### 0. 遵循 ServiceDef 代码风格规范
+
+> 📐 **重要**: 请阅读 [ServiceDef 代码风格规范](../best-practices/service-definition.md)，了解两条核心规则：
+> 1. ServiceDef 必须声明为独立变量，禁止内联在 `serviceDefs` 数组中
+> 2. ServiceDef 声明必须与实现类放在同一个文件中
+
 ### 1. 组件拆分
 
 ```