# art-api

**Repository Path**: gao_qin_fei/art-api

## Basic Information

- **Project Name**: art-api
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-13
- **Last Updated**: 2025-10-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Art API 项目

基于 Laravel 9 构建的现代化 RESTful API 服务，采用完全前后端分离架构。

## 🚀 项目特色

- ✅ **双 API 架构**: 前端用户 API (`/api`) + 后台管理 API (`/admin-api`)
- ✅ **完全前后端分离**: 纯 API 服务，支持任何前端框架
- ✅ **JWT 认证**: 基于 Laravel Sanctum 的安全认证
- ✅ **统一响应格式**: 标准化的 JSON 响应
- ✅ **版本控制**: API 版本化管理
- ✅ **权限管理**: 细粒度的权限控制
- ✅ **开发友好**: 完整的 API 文档和示例

## 📋 技术栈

- **后端**: PHP 8.0+ / Laravel 9
- **认证**: Laravel Sanctum
- **数据库**: MySQL / PostgreSQL / SQLite
- **缓存**: Redis (可选)
- **前端**: 任意框架 (Vue.js, React, Angular 等)

## 🏗️ 架构设计

### API 路由结构

```
前端用户 API:
├── /api/health                    # 健康检查
├── /api/docs                      # API 文档 (开发环境)
└── /api/v1/                       # 版本化 API
    ├── auth/                      # 用户认证
    │   ├── POST register          # 用户注册
    │   ├── POST login             # 用户登录
    │   ├── POST logout            # 用户登出
    │   ├── GET me                 # 获取当前用户
    │   ├── POST refresh           # 刷新令牌
    │   └── POST change-password   # 修改密码
    └── users/                     # 用户管理
        ├── GET /                  # 获取用户列表
        ├── POST /                 # 创建用户
        ├── GET /{id}              # 获取用户详情
        ├── PUT /{id}              # 更新用户
        ├── DELETE /{id}           # 删除用户
        └── POST batch-destroy     # 批量删除

后台管理 API:
├── /admin-api/health              # 健康检查
├── /admin-api/docs                # API 文档 (开发环境)
├── /admin-api/dashboard/          # 仪表盘
│   ├── GET /                      # 仪表盘概览
│   ├── GET user-growth            # 用户增长数据
│   ├── GET quick-stats            # 快速统计
│   ├── GET health-check           # 系统健康检查
│   ├── GET user-activity-logs     # 用户活动日志
│   └── POST clear-cache           # 清除缓存
└── /admin-api/users/              # 用户管理
    ├── GET /                      # 获取用户列表
    ├── POST /                     # 创建用户
    ├── GET /{id}                  # 获取用户详情
    ├── PUT /{id}                  # 更新用户
    ├── DELETE /{id}               # 删除用户
    ├── POST batch-destroy         # 批量删除
    ├── POST /{id}/reset-password  # 重置密码
    ├── POST /{id}/toggle-status   # 切换状态
    └── GET export/data            # 导出数据
```

## 🛠️ 快速开始

### 环境要求
- PHP >= 8.0.2
- Composer
- MySQL/PostgreSQL/SQLite
- Node.js & NPM (前端开发)

### 安装步骤

1. **克隆项目**
```bash
git clone <repository-url> art-api
cd art-api
```

2. **安装依赖**
```bash
composer install
npm install
```

3. **环境配置**
```bash
cp .env.example .env
php artisan key:generate
```

4. **数据库配置**
```env
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=art_api
DB_USERNAME=root
DB_PASSWORD=your_password
```

5. **数据库迁移**
```bash
php artisan migrate
php artisan db:seed  # 可选：填充测试数据
```

6. **启动服务**
```bash
# 后端 API 服务
php artisan serve

# 前端资源构建 (如需要)
npm run dev
```

## 📖 API 使用指南

### 认证流程

#### 1. 用户注册
```javascript
// POST /api/v1/auth/register
const response = await fetch('/api/v1/auth/register', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({
        name: 'John Doe',
        email: 'john@example.com',
        password: 'password123',
        password_confirmation: 'password123'
    })
});

const data = await response.json();
// 返回: { code: 201, message: "注册成功", data: { user: {...}, token: "..." } }
```

#### 2. 用户登录
```javascript
// POST /api/v1/auth/login
const response = await fetch('/api/v1/auth/login', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({
        email: 'john@example.com',
        password: 'password123'
    })
});

const data = await response.json();
// 保存 token 用于后续请求
localStorage.setItem('token', data.data.token);
```

#### 3. 认证请求
```javascript
// 所有需要认证的请求都需要携带 token
const token = localStorage.getItem('token');

const response = await fetch('/api/v1/auth/me', {
    headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json',
    }
});
```

### 前端集成示例

#### Vue.js 集成
```javascript
// api.js
import axios from 'axios';

const api = axios.create({
    baseURL: '/api/v1',
    headers: {
        'Content-Type': 'application/json',
    }
});

// 请求拦截器 - 添加认证头
api.interceptors.request.use(config => {
    const token = localStorage.getItem('token');
    if (token) {
        config.headers.Authorization = `Bearer ${token}`;
    }
    return config;
});

// 响应拦截器 - 处理统一响应格式
api.interceptors.response.use(
    response => {
        const { code, message, data } = response.data;
        if (code >= 200 && code < 300) {
            return data; // 直接返回 data 部分
        } else {
            return Promise.reject({ code, message, data });
        }
    },
    error => {
        if (error.response?.data?.code === 401) {
            localStorage.removeItem('token');
            window.location.href = '/login';
        }
        return Promise.reject(error.response?.data || { code: 0, message: '网络错误' });
    }
);

export default api;
```

#### React 集成
```javascript
// hooks/useAuth.js
import { useState, useEffect } from 'react';

export const useAuth = () => {
    const [user, setUser] = useState(null);
    const [loading, setLoading] = useState(true);

    useEffect(() => {
        const token = localStorage.getItem('token');
        if (token) {
            fetchUser();
        } else {
            setLoading(false);
        }
    }, []);

    const fetchUser = async () => {
        try {
            const response = await fetch('/api/v1/auth/me', {
                headers: {
                    'Authorization': `Bearer ${localStorage.getItem('token')}`
                }
            });
            const data = await response.json();
            if (data.success) {
                setUser(data.data);
            }
        } catch (error) {
            console.error('获取用户信息失败:', error);
        } finally {
            setLoading(false);
        }
    };

    const login = async (credentials) => {
        const response = await fetch('/api/v1/auth/login', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(credentials)
        });
        const data = await response.json();
        
        if (data.success) {
            localStorage.setItem('token', data.data.token);
            setUser(data.data.user);
            return true;
        }
        return false;
    };

    const logout = () => {
        localStorage.removeItem('token');
        setUser(null);
    };

    return { user, loading, login, logout };
};
```

### 后台管理 API 使用

#### 仪表盘数据
```javascript
// 获取仪表盘概览
const dashboard = await fetch('/admin-api/dashboard', {
    headers: { 'Authorization': `Bearer ${adminToken}` }
});

// 获取用户增长趋势
const growth = await fetch('/admin-api/dashboard/user-growth?days=30', {
    headers: { 'Authorization': `Bearer ${adminToken}` }
});
```

#### 用户管理
```javascript
// 获取用户列表 (支持分页和搜索)
const users = await fetch('/admin-api/users?page=1&per_page=20&search=john', {
    headers: { 'Authorization': `Bearer ${adminToken}` }
});

// 重置用户密码
const reset = await fetch('/admin-api/users/123/reset-password', {
    method: 'POST',
    headers: { 
        'Authorization': `Bearer ${adminToken}`,
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({ password: 'newpassword123' })
});
```

## 🔒 权限系统

### 认证中间件
- `auth:sanctum`: 用户认证
- `admin.auth`: 管理员认证 (基于用户角色)

### 权限检查
```php
// 在控制器中检查权限
public function index(Request $request)
{
    // 检查是否为管理员
    if (!$request->user()->isAdmin()) {
        return response()->json([
            'success' => false,
            'message' => '权限不足'
        ], 403);
    }
    
    // 继续处理...
}
```

## 📊 响应格式

### 统一响应格式
所有 API 接口都遵循统一的响应格式，包含三个必需字段：`code`、`message`、`data`。

### 成功响应
```json
{
    "code": 200,
    "message": "操作成功",
    "data": {
        // 实际数据
    }
}
```

### 分页响应
```json
{
    "code": 200,
    "message": "获取数据成功",
    "data": {
        "items": [
            // 数据项
        ],
        "pagination": {
            "current_page": 1,
            "per_page": 15,
            "total": 100,
            "last_page": 7,
            "from": 1,
            "to": 15
        }
    }
}
```

### 错误响应
```json
{
    "code": 422,
    "message": "数据验证失败",
    "data": {
        "errors": {
            "field": ["具体错误描述"]
        }
    }
}
```

## 🚀 部署指南

### 生产环境配置

1. **环境变量**
```env
APP_ENV=production
APP_DEBUG=false
APP_URL=https://your-domain.com

# 数据库配置
DB_CONNECTION=mysql
DB_HOST=your-db-host
DB_DATABASE=art_api_prod

# 缓存配置
CACHE_DRIVER=redis
REDIS_HOST=your-redis-host
```

2. **优化命令**
```bash
# 安装生产依赖
composer install --optimize-autoloader --no-dev

# 缓存配置
php artisan config:cache
php artisan route:cache
php artisan view:cache

# 数据库迁移
php artisan migrate --force
```

3. **Web 服务器配置 (Nginx)**
```nginx
server {
    listen 80;
    server_name your-domain.com;
    root /path/to/art-api/public;
    index index.php;

    # API 路由
    location /api/ {
        try_files $uri $uri/ /index.php?$query_string;
    }

    # Admin API 路由
    location /admin-api/ {
        try_files $uri $uri/ /index.php?$query_string;
    }

    # PHP 处理
    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.0-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }
}
```

## 🔧 开发工具

### API 测试
```bash
# 健康检查
curl http://localhost:8000/api/health
curl http://localhost:8000/admin-api/health

# 用户注册
curl -X POST http://localhost:8000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"name":"Test User","email":"test@example.com","password":"password123","password_confirmation":"password123"}'

# 用户登录
curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"password123"}'
```

### 代码质量
```bash
# 代码格式化
./vendor/bin/pint

# 运行测试
php artisan test

# 生成 API 文档 (如果安装了相关包)
php artisan l5-swagger:generate
```

## 📚 扩展开发

### 添加新的 API 端点

1. **创建控制器**
```bash
php artisan make:controller Api/V1/ArticleController --api
```

2. **添加路由**
```php
// routes/api.php
Route::middleware('auth:sanctum')->group(function () {
    Route::apiResource('articles', ArticleController::class);
});
```

3. **创建请求验证**
```bash
php artisan make:request Api/StoreArticleRequest
```

### 添加后台管理功能

1. **创建管理控制器**
```bash
php artisan make:controller Admin/ArticleController
```

2. **添加管理路由**
```php
// routes/admin-api.php
Route::middleware('auth:sanctum')->group(function () {
    Route::prefix('articles')->group(function () {
        Route::get('/', [ArticleController::class, 'index']);
        Route::post('/', [ArticleController::class, 'store']);
        // ... 其他路由
    });
});
```

## 🤝 贡献指南

1. Fork 项目
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 📞 支持

- 📧 邮箱: support@example.com
- 📖 文档: [项目文档](https://docs.example.com)
- 🐛 问题反馈: [GitHub Issues](https://github.com/your-repo/issues)

---

**Happy Coding! 🎉**