---
title: 通知 API | 用户通知管理接口 - MengStack官方文档
---

# 通知接口

所有接口需要认证，并携带 `X-Tenant-ID` 头。

## 创建通知

**`POST /api/v1/notifications`**

### 请求体

```json
{
  "user_id": 1,
  "title": "欢迎加入",
  "content": "您的账号已成功创建。",
  "type": "info"
}
```

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `user_id` | int | 是 | 接收用户 ID |
| `title` | string | 是 | 通知标题 |
| `content` | string | 否 | 通知内容 |
| `type` | string | 否 | 类型：info / success / warning / error，默认 info |

### 响应

返回 `NotificationDTO`。

---

## 获取通知详情

**`GET /api/v1/notifications/:id`**

### 路径参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `id` | int | 通知 ID |

---

## 获取用户通知列表

**`GET /api/v1/notifications/user/:userId`**

### 路径参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `userId` | int | 用户 ID |

### 查询参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `page` | int | 否 | 页码，默认 1 |
| `page_size` | int | 否 | 每页条数，默认 20 |

### 响应

```json
{
  "code": 0,
  "data": {
    "items": [
      {
        "id": 1,
        "tenant_id": "550e8400-...",
        "user_id": 1,
        "title": "欢迎加入",
        "content": "您的账号已成功创建。",
        "type": "info",
        "is_read": false,
        "created_at": "2026-10-03T10:00:00+08:00"
      }
    ],
    "total": 15,
    "page": 1
  }
}
```

---

## 标记通知已读

**`PUT /api/v1/notifications/:id/read`**

### 路径参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `id` | int | 通知 ID |

---

## 全部标记已读

**`PUT /api/v1/notifications/read-all`**

将当前用户（从 JWT 提取）的所有通知标记为已读。

---

## 获取未读数量

**`GET /api/v1/notifications/unread-count`**

### 响应

```json
{
  "code": 0,
  "data": {
    "count": 5
  }
}
```

---

## 删除通知

**`DELETE /api/v1/notifications/:id`**

### 路径参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `id` | int | 通知 ID |