# 前端通用模板

**Repository Path**: hanser_wei_admin/front-end-universal-template

## Basic Information

- **Project Name**: 前端通用模板
- **Description**: 提供前端开发基础框架与于接口生成工具，支持快速搭建Web应用，涵盖多种布局与交互效果，助力开发者高效实现项目目标。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-25
- **Last Updated**: 2025-09-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 新社区前端项目

本项目是一个基于 Vue 3, Vite, TypeScript 和 Pinia 的现代化前端项目模板。

## ✨ 特性

- **技术栈**: Vue 3, Vite, TypeScript, Pinia
- **UI 框架**: (请在此处填写您使用的UI框架, e.g., Element Plus, Naive UI)
- **代码规范**: Prettier, ESLint
- **HTTP 请求**: Axios
- **API 代码生成**: Orval

## 🚀 快速开始

1.  **安装依赖**

    ```bash
    pnpm install
    ```

2.  **启动开发服务器**

    ```bash
    pnpm dev
    ```

3.  **打包构建**

    ```bash
    pnpm build
    ```

## 📂 目录结构

```
.
├── public/              # 静态资源目录
├── src/
│   ├── api/             # Orval 自动生成的 API 代码
│   │   ├── *-controller/  # 按后端 Controller (tag) 拆分的 API 文件
│   │   └── models/        # 后端返回的数据结构 (DTOs/VOs)
│   ├── router/          # 路由配置
│   ├── stores/          # Pinia 状态管理
│   ├── App.vue          # 根组件
│   ├── main.ts          # 应用入口文件
│   └── axios-instance.ts# 自定义的 Axios 实例
├── .env.development     # 开发环境变量
├── .env.production      # 生产环境变量
├── eslint.config.ts     # ESLint 配置文件
├── orval.config.ts      # Orval 配置文件
├── package.json         # 项目依赖和脚本
└── tsconfig.json        # TypeScript 配置文件
```

## 💡 API 接口使用指南

本项目使用 [Orval](https://orval.dev/) 根据后端 OpenAPI 规范自动生成类型安全的API请求代码。所有API相关文件都位于 `src/api` 目录下。

### 如何使用

API已经按照后端Controller进行了分组，例如 `user-controller` 相关的接口都在 `src/api/user-controller/user-controller.ts` 文件中。

由于我们配置了自定义的 Axios 实例，该实例的响应拦截器会自动解析并返回 `response.data`。因此，您调用API函数后得到的就是后端返回的实际数据体，无需再进行 `.data` 的提取。

**示例：查询用户列表**

假设我们需要调用 `user-controller` 中的 `listUserByPage` 接口来获取用户分页数据。

```typescript
<script setup lang="ts">
import { onMounted, ref } from 'vue'
// 1. 从对应的 controller 中导入 API 函数和所需的参数/返回类型
import { listUserByPage } from '@/api/user-controller/user-controller'
import type { User, UserQueryRequest } from '@/api/models'

const userList = ref<User[]>([])

const fetchUserList = async () => {
  try {
    // 2. 准备请求参数
    const params: UserQueryRequest = {
      current: 1,
      pageSize: 10,
      // 其他查询参数...
    };

    // 3. 调用 API 函数，并使用 await 等待结果
    // 返回值已经是后端接口定义的 PageData<User> 类型，无需 .data
    const response = await listUserByPage(params);

    // 4. 更新状态
    if (response.records) {
      userList.value = response.records;
    }

  } catch (error) {
    console.error('获取用户列表失败:', error);
  }
}

onMounted(() => {
  fetchUserList();
})
</script>
```

### 更新 API

当后端接口发生变化时，您可能需要重新生成 API 代码。通常可以在 `package.json` 中配置一个脚本来执行此操作（如果尚未配置）。

```bash
# 假设在 package.json 中配置了 "generate:api": "orval"
pnpm generate:api
```