wqyblog_api_go/README.md

# 博客 RESTful API 文档

## 简介

本 API 提供了一个用于管理博客文章的接口，支持使用 Markdown 格式存储内容，并且支持分页查询。后端基于 Go 语言开发，支持 MySQL 和 PostgreSQL 数据库。

## 基本信息

- **Base URL**: `https://func-e-wiwafluoqc.cn-shanghai.fcapp.run/api`
- **Content-Type**: `application/json`
- **Authorization**: 使用 JWT 进行身份验证。在所有需要身份验证的请求中，必须在请求头中包含 `Authorization: Bearer {token}`。

## 测试认证密码

- **用户名**: `admin`
- **密码**: `123456@321`

## 认证

### 1. 用户登录

**描述**: 生成一个 JWT，用于后续的 API 调用。

- **URL**: `/auth/login`
- **方法**: `POST`
- **请求体**:
    ```json
    {
        "username": "admin",
        "password": "your_secure_password"
    }
    ```
- **响应**:
    ```json
    {
        "token": "jwt_token"
    }
    ```
- **说明**: 成功登录后，返回 JWT 令牌，用于后续请求的身份认证。

## 博文管理

### 2. 获取博文列表

**描述**: 获取博客文章列表，支持分页。

- **URL**: `/posts`
- **方法**: `GET`
- **请求参数**:
    - `page` (可选): 页码，默认值为 `1`。
    - `limit` (可选): 每页显示的记录数量，默认值为 `10`。
- **响应**:
    ```json
    {
        "page": 1,
        "limit": 10,
        "data": [
            {
                "ID": 1,
                "CreatedAt": "2024-08-20T12:00:00Z",
                "UpdatedAt": "2024-08-20T12:00:00Z",
                "DeletedAt": null,
                "Title": "First Post",
                "Content": "Markdown content here..."
            }
        ]
    }
    ```
- **说明**: 返回分页后的博文列表。

### 3. 获取单个博文

**描述**: 根据 `id` 获取指定的博客文章。

- **URL**: `/posts/:id`
- **方法**: `GET`
- **响应**:
    ```json
    {
        "ID": 1,
        "CreatedAt": "2024-08-20T12:00:00Z",
        "UpdatedAt": "2024-08-20T12:00:00Z",
        "DeletedAt": null,
        "Title": "First Post",
        "Content": "Markdown content here..."
    }
    ```
- **说明**: 返回指定 `id` 的博文详情。如果该 `id` 对应的博文不存在，返回 `404` 错误。

### 4. 创建博文

**描述**: 创建一篇新的博客文章。

- **URL**: `/posts`
- **方法**: `POST`
- **请求体**:
    ```json
    {
        "title": "New Post Title",
        "content": "Markdown content here..."
    }
    ```
- **响应**:
    ```json
    {
        "ID": 3,
        "CreatedAt": "2024-08-22T12:00:00Z",
        "UpdatedAt": "2024-08-22T12:00:00Z",
        "DeletedAt": null,
        "Title": "New Post Title",
        "Content": "Markdown content here..."
    }
    ```
- **说明**: 创建一篇新的博文，并返回创建的博文信息。

### 5. 更新博文

**描述**: 更新指定 `id` 的博客文章。

- **URL**: `/posts/:id`
- **方法**: `PUT`
- **请求体**:
    ```json
    {
        "title": "Updated Post Title",
        "content": "Updated markdown content..."
    }
    ```
- **响应**:
    ```json
    {
        "ID": 1,
        "CreatedAt": "2024-08-20T12:00:00Z",
        "UpdatedAt": "2024-08-22T13:00:00Z",
        "DeletedAt": null,
        "Title": "Updated Post Title",
        "Content": "Updated markdown content..."
    }
    ```
- **说明**: 更新指定 `id` 的博文。如果该 `id` 对应的博文不存在，返回 `404` 错误。

### 6. 删除博文

**描述**: 删除指定 `id` 的博客文章。

- **URL**: `/posts/:id`
- **方法**: `DELETE`
- **响应**:
    ```json
    {
        "message": "Post deleted successfully"
    }
    ```
- **说明**: 删除指定 `id` 的博文。如果该 `id` 对应的博文不存在，返回 `404` 错误。

## 错误处理

API 在发生错误时会返回以下格式的错误响应：

```json
{
    "error": "Error description"
}
```

- **401 Unauthorized**: 需要有效的 JWT 令牌，但令牌未提供或无效。
- **404 Not Found**: 请求的资源不存在（如博文不存在）。
- **400 Bad Request**: 请求参数无效或缺失。

## 例外情况

在使用此 API 时，请确保使用 HTTPS 来保护数据传输的安全性。