using Dpz.Core.Public.ViewModel.Response;

namespace Dpz.Core.WebApi.Controllers;

/// <summary>
/// 系统通知管理
/// </summary>
[ApiController, Route("api/[controller]"), Authorize(nameof(Permissions.System))]
public class SystemNotificationController(ISystemNotificationHistoryService notificationService)
    : ControllerBase
{
    /// <summary>
    /// 获取最近的系统通知
    /// </summary>
    [HttpGet, AllowAnonymous]
    [ProducesResponseType<List<SystemNotificationHistoryResponse>>(StatusCodes.Status200OK)]
    public async Task<IActionResult> GetLatest(CancellationToken cancellationToken = default)
    {
        var list = await notificationService.GetRecentAsync(cancellationToken);
        return Ok(list);
    }

    /// <summary>
    /// 分页获取系统通知记录
    /// </summary>
    /// <param name="query">查询参数</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns></returns>
    [HttpGet("page")]
    [ProducesResponseType<List<SystemNotificationHistoryResponse>>(StatusCodes.Status200OK)]
    [ProducesResponseType(StatusCodes.Status401Unauthorized)]
    public async Task<IActionResult> GetPage(
        [FromQuery] SystemNotificationQueryDto query,
        CancellationToken cancellationToken = default
    )
    {
        var list = await notificationService.GetPageAsync(
            query.PageIndex,
            query.PageSize,
            cancellationToken
        );
        list.AddPaginationMetadata(Response.Headers);
        return Ok(list);
    }

    /// <summary>
    /// 删除系统通知记录
    /// </summary>
    /// <param name="id">记录 ID</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns></returns>
    [HttpDelete("{id}")]
    [ProducesResponseType(StatusCodes.Status204NoContent)]
    [ProducesResponseType(StatusCodes.Status401Unauthorized)]
    public async Task<IActionResult> Delete(
        string id,
        CancellationToken cancellationToken = default
    )
    {
        await notificationService.DeleteAsync(id, cancellationToken);
        return NoContent();
    }
}
⚠⚠    以下内容为AI分析的结果,请根据实际情况进行判断。

这是一个基于 ASP.NET Core 的 Web API 控制器,用于管理系统通知功能。让我详细解释一下这个代码:

类定义和依赖注入

[ApiController, Route("api/[controller]"), Authorize(nameof(Permissions.System))]
public class SystemNotificationController(ISystemNotificationHistoryService notificationService)
    : ControllerBase
  • 特性标注

    • [ApiController]:启用 API 控制器特性,提供模型验证、自动 HTTP 400 响应等功能
    • [Route("api/[controller]")]:设置路由模板为 api/SystemNotification
    • [Authorize(nameof(Permissions.System))]:要求系统权限才能访问(除非特别标注 AllowAnonymous
  • 构造函数注入:使用 C# 12 的主构造函数语法,注入 ISystemNotificationHistoryService 服务

API 端点分析

1. 获取最新通知 (GET /api/SystemNotification)

[HttpGet, AllowAnonymous]
[ProducesResponseType<List<SystemNotificationHistoryResponse>>(StatusCodes.Status200OK)]
public async Task<IActionResult> GetLatest(CancellationToken cancellationToken = default)
  • 访问控制AllowAnonymous 允许匿名访问,覆盖了类级别的授权要求
  • 返回类型:返回系统通知历史记录列表
  • 用途:获取最近的系统通知,通常用于首页或公告展示

2. 分页获取通知记录 (GET /api/SystemNotification/page)

[HttpGet("page")]
[ProducesResponseType<List<SystemNotificationHistoryResponse>>(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status401Unauthorized)]
public async Task<IActionResult> GetPage([FromQuery] SystemNotificationQueryDto query, ...)
  • 查询参数:通过 FromQuery 绑定查询字符串到 DTO 对象
  • 分页功能:调用服务层的分页方法,并将分页元数据添加到响应头
  • 权限控制:需要系统权限,未授权返回 401

3. 删除通知记录 (DELETE /api/SystemNotification/{id})

[HttpDelete("{id}")]
[ProducesResponseType(StatusCodes.Status204NoContent)]
[ProducesResponseType(StatusCodes.Status401Unauthorized)]
public async Task<IActionResult> Delete(string id, ...)
  • 路由参数:通过 URL 路径获取要删除的记录 ID
  • 返回状态:成功删除返回 204 No Content
  • 权限控制:需要系统权限

设计特点

  1. 异步编程:所有方法都使用 async/await 模式,支持取消令牌
  2. RESTful 设计:遵循 REST API 设计原则
  3. 响应类型声明:使用 ProducesResponseType 特性明确 API 响应类型,便于 Swagger 文档生成
  4. 权限分层:类级别权限控制 + 方法级别例外处理
  5. 依赖注入:通过构造函数注入服务,便于测试和解耦

功能用途

这个控制器主要用于:

  • 系统公告/通知的展示(支持匿名访问)
  • 管理员对通知历史记录的管理(需要系统权限)
  • 支持分页查询大量通知数据
  • 提供通知记录的删除功能

整体来看,这是一个设计良好的现代 Web API 控制器,遵循了最佳实践。

评论加载中...