@qlover/create-app 0.6.0 → 0.6.2

package/dist/templates/react-app/docs/zh/ioc.md

@@ -0,0 +1,410 @@
+# IOC 容器
+
+## 什么是 IOC？
+
+IOC（Inversion of Control，控制反转）是一种设计模式，它将对象的创建和依赖关系的管理交给容器来处理，而不是在代码中直接创建对象。
+
+**简单来说**：就像工厂生产产品一样，你不需要知道产品是如何制造的，只需要告诉工厂你需要什么产品，工厂就会给你提供。
+
+## 项目中的 IOC 实现
+
+### 核心技术栈
+
+- **InversifyJS**：作为 IOC 容器的实现(你也可以手动实现自己的容器)
+- **TypeScript**：提供类型安全
+- **装饰器模式**：使用 `@injectable()` 和 `@inject()` 装饰器
+
+### 核心文件结构
+
+```
+src/
+├── core/
+│   ├── IOC.ts                    # IOC 主入口
+│   ├── registers/                 # 注册器目录
+│   │   ├── RegisterGlobals.ts    # 全局服务注册
+│   │   ├── RegisterCommon.ts     # 通用服务注册
+│   │   └── RegisterControllers.ts # 控制器注册
+│   └── globals.ts                # 全局实例
+├── base/
+│   └── cases/
+│       └── InversifyContainer.ts # Inversify 容器实现
+└── config/
+    └── IOCIdentifier.ts          # IOC 标识符定义
+```
+
+## 基本概念
+
+### 1. IOC 标识符
+
+```tsx
+// config/IOCIdentifier.ts
+export const IOCIdentifier = Object.freeze({
+  JSON: 'JSON',
+  LocalStorage: 'LocalStorage',
+  Logger: 'Logger',
+  AppConfig: 'AppConfig',
+  // ... 更多标识符
+});
+```
+
+### 2. IOC 标识符映射
+
+```tsx
+// core/IOC.ts
+export interface IOCIdentifierMap {
+  [IOCIdentifier.JSON]: import('@qlover/fe-corekit').JSONSerializer;
+  [IOCIdentifier.LocalStorage]: import('@qlover/fe-corekit').ObjectStorage<string, string>;
+  [IOCIdentifier.Logger]: import('@qlover/logger').LoggerInterface;
+  [IOCIdentifier.AppConfig]: import('@qlover/corekit-bridge').EnvConfigInterface;
+  // ... 更多映射
+}
+```
+
+### 3. IOC 函数
+
+```tsx
+// core/IOC.ts
+export const IOC = createIOCFunction<IOCIdentifierMap>(
+  new InversifyContainer()
+);
+```
+
+## 使用方法
+
+### 1. 获取服务实例
+
+```tsx
+// 使用类名获取
+const userService = IOC(UserService);
+
+// 使用字符串标识符获取
+const logger = IOC('Logger');
+// 或者
+const logger = IOC(IOCIdentifier.Logger);
+
+// 使用 AppConfig
+const appConfig = IOC(IOCIdentifier.AppConfig);
+```
+
+### 2. 在服务中使用依赖注入
+
+```tsx
+import { inject, injectable } from 'inversify';
+import { UserApi } from '@/base/apis/userApi/UserApi';
+import { RouteService } from './RouteService';
+import { IOCIdentifier } from '@config/IOCIdentifier';
+
+@injectable()
+export class UserService extends UserAuthService<UserInfo> {
+  constructor(
+    @inject(RouteService) protected routerService: RouteService,
+    @inject(UserApi) userApi: UserAuthApiInterface<UserInfo>,
+    @inject(IOCIdentifier.AppConfig) appConfig: AppConfig,
+    @inject(IOCIdentifier.LocalStorageEncrypt) storage: SyncStorageInterface<string, string>
+  ) {
+    super(userApi, {
+      userStorage: {
+        key: appConfig.userInfoStorageKey,
+        storage: storage
+      },
+      credentialStorage: {
+        key: appConfig.userTokenStorageKey,
+        storage: storage
+      }
+    });
+  }
+}
+```
+
+### 3. 在 Bootstrap 中使用
+
+```tsx
+// 在启动器中注册服务
+bootstrap.use([
+  IOC(UserService),        // 用户服务
+  IOC(I18nService),        // 国际化服务
+  new UserApiBootstarp()   // API 配置
+]);
+```
+
+## 服务注册
+
+### 1. 全局服务注册
+
+```tsx
+// core/registers/RegisterGlobals.ts
+export const RegisterGlobals: IOCRegister = {
+  register(container, _, options): void {
+    // 注册应用配置
+    container.bind(IOCIdentifier.AppConfig, options!.appConfig);
+    
+    // 注册日志服务
+    container.bind(Logger, logger);
+    container.bind(IOCIdentifier.Logger, logger);
+    
+    // 注册存储服务
+    container.bind(IOCIdentifier.LocalStorage, localStorage);
+    container.bind(IOCIdentifier.LocalStorageEncrypt, localStorageEncrypt);
+    container.bind(IOCIdentifier.CookieStorage, cookieStorage);
+  }
+};
+```
+
+### 2. 通用服务注册
+
+```tsx
+// core/registers/RegisterCommon.ts
+export const RegisterCommon: IOCRegister = {
+  register(container, _, options): void {
+    const AppConfig = container.get(IOCIdentifier.AppConfig);
+
+    // 注册 API 相关服务
+    const feApiToken = new TokenStorage(AppConfig.userTokenStorageKey, {
+      storage: container.get(IOCIdentifier.LocalStorageEncrypt)
+    });
+    
+    container.bind(IOCIdentifier.FeApiToken, feApiToken);
+    container.bind(IOCIdentifier.FeApiCommonPlugin, feApiRequestCommonPlugin);
+    
+    // 注册主题服务
+    container.bind(ThemeService, new ThemeService({
+      ...themeConfig,
+      storage: localStorage
+    }));
+    
+    // 注册路由服务
+    container.bind(RouteService, new RouteService({
+      routes: baseRoutes,
+      logger
+    }));
+    
+    // 注册国际化服务
+    container.bind(I18nService, new I18nService(options!.pathname));
+  }
+};
+```
+
+### 3. 控制器注册
+
+```tsx
+// core/registers/RegisterControllers.ts
+export class RegisterControllers implements IOCRegister {
+  register(container: IOCContainer, _: IOCManagerInterface<IOCContainer>): void {
+    // 注册控制器
+    const jsonStorageController = new JSONStorageController(localStorage);
+    container.bind(JSONStorageController, jsonStorageController);
+
+    // 配置处理器
+    container
+      .get(ProcesserExecutor)
+      .use(container.get(I18nKeyErrorPlugin))
+      .use(container.get(UserService));
+  }
+}
+```
+
+## 实际应用场景
+
+### 1. 用户认证服务
+
+```tsx
+@injectable()
+export class UserService extends UserAuthService<UserInfo> {
+  constructor(
+    @inject(RouteService) protected routerService: RouteService,
+    @inject(UserApi) userApi: UserAuthApiInterface<UserInfo>,
+    @inject(IOCIdentifier.AppConfig) appConfig: AppConfig,
+    @inject(IOCIdentifier.LocalStorageEncrypt) storage: SyncStorageInterface<string, string>
+  ) {
+    super(userApi, {
+      userStorage: {
+        key: appConfig.userInfoStorageKey,
+        storage: storage
+      },
+      credentialStorage: {
+        key: appConfig.userTokenStorageKey,
+        storage: storage
+      }
+    });
+  }
+
+  async onBefore(): Promise<void> {
+    if (this.isAuthenticated()) {
+      return;
+    }
+
+    const userToken = this.getToken();
+    if (!userToken) {
+      throw new AppError('NO_USER_TOKEN');
+    }
+
+    await this.userInfo();
+    this.store.authSuccess();
+  }
+}
+```
+
+### 2. API 配置服务
+
+```tsx
+export class UserApiBootstarp implements BootstrapExecutorPlugin {
+  readonly pluginName = 'UserApiBootstarp';
+
+  onBefore({ parameters: { ioc } }: BootstrapContext): void {
+    // 通过 IOC 获取 UserApi 实例并配置插件
+    ioc
+      .get<UserApi>(UserApi)
+      .usePlugin(new FetchURLPlugin())
+      .usePlugin(IOC.get(IOCIdentifier.ApiMockPlugin))
+      .usePlugin(IOC.get(RequestLogger));
+  }
+}
+```
+
+### 3. 在组件中使用
+
+```tsx
+// 在 React 组件中使用 IOC 服务
+function UserProfile() {
+  const userService = IOC(UserService);
+  const { user } = useStore(userService.store);
+
+  return (
+    <div>
+      <h1>欢迎, {user?.name}</h1>
+      <button onClick={() => userService.logout()}>退出登录</button>
+    </div>
+  );
+}
+```
+
+## 最佳实践
+
+### 1. 服务设计原则
+
+```tsx
+// ✅ 好的设计：单一职责
+@injectable()
+export class UserService {
+  constructor(
+    @inject(UserApi) private userApi: UserApi,
+    @inject(IOCIdentifier.AppConfig) private appConfig: AppConfig
+  ) {}
+  
+  async getUserInfo(): Promise<UserInfo> {
+    return this.userApi.getUserInfo();
+  }
+}
+
+// ❌ 不好的设计：职责过多
+@injectable()
+export class BadService {
+  constructor(
+    @inject(UserApi) private userApi: UserApi,
+    @inject(RouteService) private routeService: RouteService,
+    @inject(ThemeService) private themeService: ThemeService,
+    @inject(I18nService) private i18nService: I18nService
+  ) {}
+  
+  // 一个服务做了太多事情
+  async handleUserAction(): Promise<void> {
+    // 处理用户逻辑
+    // 处理路由逻辑
+    // 处理主题逻辑
+    // 处理国际化逻辑
+  }
+}
+```
+
+### 2. 依赖注入的最佳实践
+
+```tsx
+// ✅ 使用接口而不是具体实现
+@injectable()
+export class UserService {
+  constructor(
+    @inject('UserApiInterface') private userApi: UserAuthApiInterface<UserInfo>
+  ) {}
+}
+
+// ✅ 使用标识符而不是类名
+@injectable()
+export class SomeService {
+  constructor(
+    @inject(IOCIdentifier.Logger) private logger: LoggerInterface,
+    @inject(IOCIdentifier.AppConfig) private appConfig: AppConfig
+  ) {}
+}
+```
+
+### 3. 错误处理
+
+```tsx
+@injectable()
+export class SafeService {
+  constructor(
+    @inject(IOCIdentifier.Logger) private logger: LoggerInterface
+  ) {}
+
+  async doSomething(): Promise<void> {
+    try {
+      // 业务逻辑
+    } catch (error) {
+      this.logger.error('操作失败:', error);
+      throw error;
+    }
+  }
+}
+```
+
+## 调试和测试
+
+### 1. 调试 IOC 容器
+
+```tsx
+// 检查服务是否已注册
+const container = IOC.implemention;
+const isRegistered = container.isBound(UserService);
+
+// 获取所有已注册的服务
+const bindings = container.getAll(UserService);
+```
+
+### 2. 单元测试
+
+```tsx
+import { Container } from 'inversify';
+
+describe('UserService', () => {
+  let container: Container;
+  let userService: UserService;
+
+  beforeEach(() => {
+    container = new Container();
+    
+    // 注册测试依赖
+    container.bind('UserApiInterface').toConstantValue(mockUserApi);
+    container.bind(IOCIdentifier.AppConfig).toConstantValue(mockAppConfig);
+    container.bind(IOCIdentifier.LocalStorageEncrypt).toConstantValue(mockStorage);
+    
+    userService = container.get(UserService);
+  });
+
+  it('should authenticate user successfully', async () => {
+    const result = await userService.onBefore();
+    expect(result).toBeDefined();
+  });
+});
+```
+
+## 总结
+
+IOC 容器在项目中的作用：
+
+1. **依赖管理**：统一管理所有服务的依赖关系
+2. **类型安全**：通过 TypeScript 提供编译时类型检查
+3. **可测试性**：便于进行单元测试和模拟
+4. **可维护性**：清晰的依赖关系，易于理解和修改
+5. **可扩展性**：轻松添加新的服务和依赖
+
+通过合理使用 IOC 容器，可以让代码更加模块化、可测试和可维护。

package/dist/templates/react-app/package.json

@@ -46,7 +46,7 @@
     "dev": "vite --mode localhost",
     "dev:staging": "vite --mode staging",
     "dev:prod": "vite --mode production",
-    "build": "vite build",
+    "build": "npm run lint && vite build",
     "lint": "tsc -b --noEmit && eslint ./src --fix",
     "prettier": "prettier --write ./src",
     "preview": "vite preview",

package/dist/templates/react-app/src/base/apis/AiApi.ts

@@ -8,11 +8,11 @@ import {
   RequestCommonPlugin
 } from '@qlover/corekit-bridge';
 import { RequestLogger } from '../cases/RequestLogger';
-import { IOCIdentifier } from '@/core/IOC';
-import { appConfig } from '@/core/globals';
+import { IOCIdentifier } from '@config/IOCIdentifier';
+import type { AppConfig } from '../cases/AppConfig';
 
 const apiApiAdapter = new RequestAdapterFetch({
-  baseURL: appConfig.aiApiBaseUrl
+  responseType: 'json'
 });
 
 // 使用 RequestScheduler
@@ -24,6 +24,11 @@ const apiApi = new RequestScheduler(apiApiAdapter);
 export const AiApiBootstarp: BootstrapExecutorPlugin = {
   pluginName: 'AiApiBootstarp',
   onBefore({ parameters: { ioc } }) {
+    const appConfig = ioc.get<AppConfig>(IOCIdentifier.AppConfig);
+
+    // dynamic set baseURL
+    apiApiAdapter.config.baseURL = appConfig.aiApiBaseUrl;
+
     apiApiAdapter.usePlugin(new FetchURLPlugin());
     apiApiAdapter.usePlugin(
       new RequestCommonPlugin({
@@ -40,13 +45,13 @@ export function aiHello(data: {
   messages: { role: string; content: string }[];
 }) {
   return apiApi.request<
-    typeof data,
     {
       id: string;
       object: string;
       created: number;
       choices: { message: { role: string; content: string } }[];
-    }
+    },
+    typeof data
   >({
     url: '/chat/completions',
     method: 'POST',

package/dist/templates/react-app/src/base/apis/feApi/FeApiAdapter.ts

@@ -1,5 +1,5 @@
 import type { AppConfig } from '@/base/cases/AppConfig';
-import { IOCIdentifier } from '@/core/IOC';
+import { IOCIdentifier } from '@config/IOCIdentifier';
 import { RequestAdapterFetch } from '@qlover/fe-corekit';
 import { inject, injectable } from 'inversify';
 

package/dist/templates/react-app/src/base/apis/feApi/FeApiBootstarp.ts

@@ -11,7 +11,7 @@ import {
   ApiPickDataPlugin
 } from '@qlover/corekit-bridge';
 import { FeApi } from './FeApi';
-import { IOCIdentifier } from '@/core/IOC';
+import { IOCIdentifier } from '@config/IOCIdentifier';
 import { RequestLogger } from '@/base/cases/RequestLogger';
 
 /**

package/dist/templates/react-app/src/base/apis/userApi/UserApi.ts

@@ -7,26 +7,21 @@ import {
   GetIpInfoTransaction,
   UserApiGetUserInfoTransaction,
   UserApiLoginTransaction,
-  UserApiTestApiCatchResultTransaction
+  UserApiTestApiCatchResultTransaction,
+  UserInfo
 } from './UserApiType';
 import { inject, injectable } from 'inversify';
 import { UserApiAdapter } from './UserApiAdapter';
 import { UserApiConfig } from './UserApiBootstarp';
-import {
+import type {
   LoginResponseData,
   UserAuthApiInterface,
-  UserAuthStoreInterface,
-  UserAuthState
+  UserAuthStoreInterface
 } from '@qlover/corekit-bridge';
-import {
-  RegisterFormData,
-  UserServiceUserInfo
-} from '@/base/services/UserService';
+import { RegisterFormData } from '@/base/services/UserService';
 import { RES_NO_TOKEN } from '@config/Identifier';
 import { AppError } from '@/base/cases/AppError';
 
-export type UserApiState = UserAuthState<UserServiceUserInfo>;
-
 /**
  * UserApi
  *
@@ -37,9 +32,9 @@ export type UserApiState = UserAuthState<UserServiceUserInfo>;
 @injectable()
 export class UserApi
   extends RequestTransaction<UserApiConfig>
-  implements UserAuthApiInterface<UserApiState>
+  implements UserAuthApiInterface<UserInfo>
 {
-  protected store: UserAuthStoreInterface<UserApiState> | null = null;
+  protected store: UserAuthStoreInterface<UserInfo> | null = null;
 
   constructor(
     @inject(FetchAbortPlugin) private abortPlugin: FetchAbortPlugin,
@@ -48,7 +43,7 @@ export class UserApi
     super(adapter);
   }
 
-  getStore(): UserAuthStoreInterface<UserApiState> | null {
+  getStore(): UserAuthStoreInterface<UserInfo> | null {
     return this.store;
   }
 
@@ -56,7 +51,7 @@ export class UserApi
    * @override
    * @param store
    */
-  setStore(store: UserAuthStoreInterface<UserApiState>): void {
+  setStore(store: UserAuthStoreInterface<UserInfo>): void {
     this.store = store;
   }
 
@@ -130,9 +125,7 @@ export class UserApi
    * @override
    * @returns
    */
-  async getUserInfo(): Promise<
-    UserApiGetUserInfoTransaction['response']['data']
-  > {
+  async getUserInfo(): Promise<UserInfo> {
     const response =
       await this.get<UserApiGetUserInfoTransaction>('/api/userinfo');
 

package/dist/templates/react-app/src/base/apis/userApi/UserApiAdapter.ts

@@ -1,5 +1,5 @@
 import type { AppConfig } from '@/base/cases/AppConfig';
-import { IOCIdentifier } from '@/core/IOC';
+import { IOCIdentifier } from '@config/IOCIdentifier';
 import { RequestAdapterFetch } from '@qlover/fe-corekit';
 import { inject, injectable } from 'inversify';
 

package/dist/templates/react-app/src/base/apis/userApi/UserApiBootstarp.ts

@@ -4,7 +4,8 @@ import {
   RequestAdapterResponse,
   RequestTransactionInterface
 } from '@qlover/fe-corekit';
-import { IOC, IOCIdentifier } from '@/core/IOC';
+import { IOC } from '@/core/IOC';
+import { IOCIdentifier } from '@config/IOCIdentifier';
 import { RequestLogger } from '@/base/cases/RequestLogger';
 import { FetchURLPlugin } from '@qlover/fe-corekit';
 import {

package/dist/templates/react-app/src/base/apis/userApi/UserApiType.ts

@@ -1,5 +1,11 @@
 import { UserApiTransaction } from './UserApiBootstarp';
 
+export type UserInfo = {
+  name: string;
+  email: string;
+  picture: string;
+};
+
 export type GetIpInfoTransaction = UserApiTransaction<
   undefined,
   {
@@ -35,11 +41,7 @@ export type UserApiGetRandomUser = UserApiTransaction<
 
 export type UserApiGetUserInfoTransaction = UserApiTransaction<
   string,
-  {
-    name: string;
-    email: string;
-    picture: string;
-  }
+  UserInfo
 >;
 
 export type UserApiLoginTransaction = UserApiTransaction<

package/dist/templates/react-app/src/base/cases/I18nKeyErrorPlugin.ts

@@ -1,14 +1,15 @@
 import type { ExecutorContext, ExecutorPlugin } from '@qlover/fe-corekit';
 import type { LoggerInterface } from '@qlover/logger';
-import { inject } from 'inversify';
+import { inject, injectable } from 'inversify';
 import { I18nService } from '../services/I18nService';
-import { IOCIdentifier } from '@/core/IOC';
+import { IOCIdentifier } from '@config/IOCIdentifier';
 
 /**
  * When throw error, it will be converted to i18n key
  *
  * If the error thrown is an i18n key, it will be converted to the corresponding text
  */
+@injectable()
 export class I18nKeyErrorPlugin implements ExecutorPlugin {
   readonly pluginName = 'I18nKeyErrorPlugin';
 

package/dist/templates/react-app/src/base/cases/InversifyContainer.ts

@@ -0,0 +1,33 @@
+import { IOCIdentifierMap } from '@/core/IOC';
+import {
+  IOCContainerInterface,
+  ServiceIdentifier
+} from '@qlover/corekit-bridge';
+import { Container } from 'inversify';
+
+export class InversifyContainer implements IOCContainerInterface {
+  private container: Container;
+
+  constructor() {
+    this.container = new Container({
+      // allow `@injectable` decorator, auto bind injectable classes
+      autobind: true,
+      // use singleton scope
+      defaultScope: 'Singleton'
+    });
+  }
+
+  bind<T>(key: ServiceIdentifier<T>, value: T): void {
+    this.container.bind<T>(key).toConstantValue(value);
+  }
+
+  get<K extends keyof IOCIdentifierMap>(
+    serviceIdentifier: K
+  ): IOCIdentifierMap[K];
+  get<T>(serviceIdentifier: ServiceIdentifier<T>): T;
+  get<T, K extends keyof IOCIdentifierMap>(
+    serviceIdentifier: ServiceIdentifier<T> | K
+  ): T | IOCIdentifierMap[K] {
+    return this.container.get<T>(serviceIdentifier);
+  }
+}

package/dist/templates/react-app/src/base/cases/RequestLogger.ts

@@ -1,4 +1,4 @@
-import { IOCIdentifier } from '@/core/IOC';
+import { IOCIdentifier } from '@config/IOCIdentifier';
 import {
   type ExecutorPlugin,
   type ExecutorContext,

package/dist/templates/react-app/src/base/cases/RequestStatusCatcher.ts

@@ -1,5 +1,5 @@
-import type { RequestCatcherInterface } from '@/base/port/RequestCatcherInterface';
-import { IOCIdentifier } from '@/core/IOC';
+import { IOCIdentifier } from '@config/IOCIdentifier';
+import type { RequestCatcherInterface } from '@qlover/corekit-bridge';
 import type { RequestAdapterResponse } from '@qlover/fe-corekit';
 import type { LoggerInterface } from '@qlover/logger';
 import { inject, injectable } from 'inversify';

package/dist/templates/react-app/src/base/services/ProcesserExecutor.ts

@@ -1,5 +1,5 @@
 import { AsyncExecutor, ExecutorPlugin } from '@qlover/fe-corekit';
-import { IOCIdentifier } from '@/core/IOC';
+import { IOCIdentifier } from '@config/IOCIdentifier';
 import { injectable, inject } from 'inversify';
 import type { LoggerInterface } from '@qlover/logger';
 import { RouteService } from './RouteService';

package/dist/templates/react-app/src/base/services/RouteService.ts

@@ -3,7 +3,10 @@ import type { NavigateFunction, NavigateOptions } from 'react-router-dom';
 import type { UIDependenciesInterface } from '@/base/port/UIDependenciesInterface';
 import type { LoggerInterface } from '@qlover/logger';
 import { I18nService } from '@/base/services/I18nService';
-import { StoreInterface, StoreStateInterface } from '@qlover/corekit-bridge';
+import {
+  StoreInterface,
+  type StoreStateInterface
+} from '@qlover/corekit-bridge';
 
 export type RouterServiceDependencies = {
   navigate: NavigateFunction;
@@ -40,7 +43,7 @@ export class RouteService
 
     if (!navigate) {
       this.logger.debug(
-        'Please use `RouterServiceProvider` to set dependencies'
+        'Please use `RouteService.setDependencies` to set dependencies'
       );
     }