Svelte 示例

概述

本示例演示如何将 ApiSorcery 与 Svelte 项目集成。Svelte 是一种构建用户界面的全新方法，采用基于编译器的架构，配合 TypeScript 支持，通过响应式状态管理提供出色的开发体验。

特性

• 类型安全：完整的 TypeScript 支持，生成接口和类型
• 响应式存储：Svelte 的响应式存储模式用于状态管理
• Axios 集成：内置支持 Axios HTTP 客户端和拦截器
• 智能提示支持：完整的 IDE 支持，包括自动完成和类型检查
• Tree shaking：通过 ES 模块支持优化打包体积

快速开始

1. 安装 ApiSorcery

npm install -g autoapi

2. 初始化配置

autoapi init -l ts

这将创建一个 .autoapirc.json 配置文件：

{
  "application": {
    "language": "ts",
    "outputDir": "./src/api/auto"
  },
  "services": [
    {
      "code": "demo",
      "token": "72735b33815c4e5c9c2a924a8f4907ef",
      "version": 3,
      "enabled": true,
      "source": "https://your-api.com/swagger.json"
    }
  ]
}

3. 安装依赖

npm install axios
npm install -D @types/node

4. 生成 API 客户端

autoapi generate

5. 在 Svelte 中使用

<script lang="ts">
  import { onMount } from 'svelte';
  import * as ApiUser from '$lib/api/auto/demo/ApiUser';
  import type { User } from '$lib/api/auto/demo/model';

  let users: User[] = [];
  let loading = false;

  async function fetchUsers() {
    loading = true;
    try {
      const res = await ApiUser.getUserPaged({
        pagination: {
          page: 1,
          limit: 10,
        },
      });
      users = res.results || [];
    } catch (error) {
      console.error('获取用户失败:', error);
    } finally {
      loading = false;
    }
  }

  onMount(() => {
    fetchUsers();
  });
</script>

<div>
  {#if loading}
    <p>加载中...</p>
  {:else}
    <ul>
      {#each users as user (user.id)}
        <li>{user.name}</li>
      {/each}
    </ul>
  {/if}
</div>

Svelte 集成模式

使用 Svelte Stores

// stores/users.ts
import { writable, derived } from 'svelte/store';
import * as ApiMain from '$lib/api/auto/demo/ApiMain';
import type { User } from '$lib/api/auto/demo/model';

function createUserStore() {
  const { subscribe, set, update } = writable<{
    data: User[];
    loading: boolean;
    error: Error | null;
  }>({
    data: [],
    loading: false,
    error: null,
  });

  return {
    subscribe,
    fetch: async () => {
      update(state => ({ ...state, loading: true, error: null }));
      try {
        const response = await ApiMain.getUsers();
        set({ data: response.data || [], loading: false, error: null });
      } catch (error) {
        update(state => ({ 
          ...state, 
          loading: false, 
          error: error as Error 
        }));
      }
    },
    reset: () => set({ data: [], loading: false, error: null }),
  };
}

export const userStore = createUserStore();

在组件中使用

<script lang="ts">
  import { onMount } from 'svelte';
  import { userStore } from '$lib/stores/users';

  onMount(() => {
    userStore.fetch();
  });

  $: ({ data: users, loading, error } = $userStore);
</script>

<div>
  {#if loading}
    <p>加载中...</p>
  {:else if error}
    <p>错误: {error.message}</p>
  {:else}
    <ul>
      {#each users as user (user.id)}
        <li>{user.name}</li>
      {/each}
    </ul>
  {/if}
  <button on:click={() => userStore.fetch()}>刷新</button>
</div>

与 SvelteKit Load 函数结合使用

// routes/users/+page.ts
import type { PageLoad } from './$types';
import * as ApiMain from '$lib/api/auto/demo/ApiMain';

export const load: PageLoad = async () => {
  try {
    const response = await ApiMain.getUsers();
    return {
      users: response.data || [],
    };
  } catch (error) {
    return {
      users: [],
      error: error instanceof Error ? error.message : '加载用户失败',
    };
  }
};

<!-- routes/users/+page.svelte -->
<script lang="ts">
  import type { PageData } from './$types';
  
  export let data: PageData;
</script>

<div>
  {#if data.error}
    <p>错误: {data.error}</p>
  {:else}
    <ul>
      {#each data.users as user (user.id)}
        <li>{user.name}</li>
      {/each}
    </ul>
  {/if}
</div>

最佳实践

1. 类型定义：利用生成的 TypeScript 接口提高类型安全性
2. 响应式存储：使用 Svelte stores 在组件之间共享状态
3. 错误处理：在 stores 和组件中实现适当的错误处理
4. 请求拦截器：使用 Axios 拦截器进行身份验证和请求/响应转换
5. 环境配置：为开发、测试和生产环境使用不同的 API 端点
6. 代码分割：实现路由和 API 模块的懒加载以优化打包体积
7. SvelteKit 集成：利用 SvelteKit 的 load 函数进行服务器端数据获取