Angular 接入教程

可直接运行的示例请参考 Angular 示例。

前置条件

• Node.js ≥ 18，Angular ≥ 17
• ApiSorcery CLI 已安装（npm i -g @apisorcery/cli）
• 设备已注册（apisorcery register）
• 已配置 .apisorceryrc.json（参考服务配置）

生成文件结构

执行 apisorcery generate 后，以下文件将创建在 outputDir（如 src/api/auto/）下：

auto/
└── {service_code}/
    ├── Api{Tag}.ts            # 每个 Swagger Tag 对应一个文件 — 勿手动修改
    ├── model.ts               # 所有请求/响应类型 — 勿手动修改
    ├── base.ts                # 基础工具 — 勿手动修改
    ├── swagger.json           # Swagger 缓存文件 — 勿手动修改
    └── httpClient/
        ├── interceptors/
        │   ├── request.ts     # ✏️ 在此添加鉴权 Token
        │   └── response.ts    # ✏️ 在此处理全局错误
        ├── requests/
        │   ├── json.ts        # JSON 请求工厂 — ✏️ 在此修改 Base URL
        │   └── blob.ts        # 文件下载工厂
        └── types/
            └── axios.d.ts

Angular HttpClient vs Axios

生成的客户端使用 Axios 而非 Angular 的 HttpClient，保持代码框架无关性，无需将 HttpClient 注入每个服务。

安装依赖

npm install axios

配置 Base URL

打开 httpClient/requests/json.ts，设置你的 API 服务地址：

const instance = axios.create({
  baseURL: 'https://your-api.com',  // ✏️ 修改这里
  timeout: 10000,
});

配置鉴权 Token

打开 httpClient/interceptors/request.ts：

instance.interceptors.request.use((config) => {
  const token = localStorage.getItem('token'); // ✏️ 替换为你自己的 Token 来源
  if (token) {
    config.headers.Authorization = `Bearer ${token}`;
  }
  return config;
});

打开 httpClient/interceptors/response.ts，处理鉴权失效：

instance.interceptors.response.use(
  (response) => response,
  (error) => {
    if (error.response?.status === 401) {
      // ✏️ 跳转到登录页
      // inject(Router).navigate(['/login']);
    }
    return Promise.reject(error);
  }
);

调用生成的 API

import { Component, OnInit } from '@angular/core';
import * as ApiUser from '../api/auto/demo/ApiUser';
import type { UserInfoDto } from '../api/auto/demo/model';

@Component({ selector: 'app-user-list', template: '...' })
export class UserListComponent implements OnInit {
  users: UserInfoDto[] = [];

  async ngOnInit() {
    this.users = await ApiUser.getUserList({ page: 1, limit: 10 });
  }
}

常见问题

returnLevel 应该选哪个？

大多数后端将响应包裹为 { code, data, message } 格式。使用默认的 "returnLevel": "second" 可自动解包 data 字段。如果你的接口直接返回数据体（无外层包裹），则使用 "returnLevel": "first"。

中文 Tag 名称导致生成的类名无法编译

在服务配置中添加 tagNameMap：

"tagNameMap": { "用户管理": "User", "订单管理": "Order" }

详见服务配置。