基于.NetCore开发博客项目 StarBlog - (22) 开发博客文章相关接口

前言

本文介绍博客文章相关接口的开发，作为接口开发介绍的第一篇，会写得比较详细，以抛砖引玉，后面的其他接口就粗略带过了，着重于WebApi开发的周边设施。

涉及到的接口：文章CRUD、置顶文章、推荐文章等。

开始前先介绍下AspNetCore框架的基础概念，MVC模式（前后端不分离）、WebApi模式（前后端分离），都是有Controller的。

区别在前者的Controller集成自 Controller 类，后者继承自 ControllerBase 类。

无论博客前台，还是接口，大部分逻辑都是通用的，因此我把这些逻辑封装在 service 中，以减少冗余代码。

文章CRUD

在之前的文章里，已经实现了文章列表、文章详情的功能，等于是CRUD里的 R (Retrieve) “查”功能已经实现。

相关代码在 StarBlog.Web/Services/PostService.cs 文件中。

PS：根据RESTFul规范，CRUD不同的操作对应不同的HTTP方法

在AspNetCore中，可以通过在 Action 上加上 [HttpPost]、[HttpDelete("{id}")] 这样的特性来标记接口使用的HTTP方法和URL。

现在需要实现“增删改”的功能。

增和改 (Create/Update)

因为这俩功能差不多，所以放在一起实现，很多ORM也是把 Insert 和 Update 合在一起，即 InsertOrUpdate

DTO

在计算机编程中，数据传输对象 (data transfer object，DTO)是在2个进程中携带数据的对象。因为进程间通信通常用于远程接口（如web服务）的昂贵操作。成本的主体是客户和服务器之间的来回通信时间。为降低这种调用次数，使用DTO聚合本来需要多次通信传输的数据。

DAO与业务对象或数据访问对象的区别是：DTO的数据的变异子与访问子（mutator和accessor）、语法分析（parser）、序列化（serializer）时不会有任何存储、获取、序列化和反序列化的异常。即DTO是简单对象，不含任何业务逻辑，但可包含序列化和反序列化以用于传输数据。

by Wikipedia

添加文章只需要 Post 模型的其中几个属性就行，不适合把整个 Post 模型作为参数，所以，首先要定义一个DTO作为添加文章的参数。

文件路径 StarBlog.Web/ViewModels/Blog/PostCreationDto.cs

public class PostCreationDto {

    /// <summary>

    /// 标题

    /// </summary>

    public string? Title { get; set; }

    /// <summary>

    /// 梗概

    /// </summary>

    public string? Summary { get; set; }

    /// <summary>

    /// 内容（markdown格式）

    /// </summary>

    public string? Content { get; set; }

    /// <summary>

    /// 分类ID

    /// </summary>

    public int CategoryId { get; set; }

}

AutoMapper

有了DTO作为参数，在保存文章的时候，我们需要手动把DTO对象里面的属性，一个个赋值到 Post 对象上，像这样：

var post = new Post {

    Id = Guid.NewGuid(),

	Title = dto.Title,

    Summary = dto.Summary,

    Content = dto.Content,

    CategoryId = dto.CategoryId

};

一个俩个还好，接口多了的话，大量重复的代码会很烦人，而且也容易出错。

还好我们可以用AutoMapper组件来实现对象自动映射。

通过nuget安装 AutoMapper.Extensions.Microsoft.DependencyInjection 这个包

注册服务：

builder.Services.AddAutoMapper(typeof(Program));

然后再创建对应的Profile（配置），如果没有特殊配置其实也可以不添加这个配置文件，执行默认的映射行为即可。

作为例子，本文简单介绍一下，创建 StarBlog.Web/Properties/AutoMapper/PostProfile.cs 文件

public class PostProfile : Profile {

    public PostProfile() {

        CreateMap<PostUpdateDto, Post>();

        CreateMap<PostCreationDto, Post>();

    }

}

在构造方法里执行 CreateMap 配置从左到右的映射关系。

上面的代码配置了从 PostUpdateDto / PostCreationDto 这两个对象到 Post 对象的映射关系。

如果有些字段不要映射的，可以这样写：

public class PostProfile : Profile {

    private readonly List<string> _unmapped = new List<string> {

        "Categories",

    };

    public PostProfile() {

        CreateMap<PostUpdateDto, Post>();

        CreateMap<PostCreationDto, Post>();

        ShouldMapProperty = property => !_unmapped.Contains(property.Name);

    }

}

其他代码不变，修改 _unmapped 这个字段就行。

接着在 Controller 里注入 IMapper 对象

private readonly IMapper _mapper;

使用方法很简单

var post = _mapper.Map<Post>(dto);

传入一个 PostCreationDto 类型的 dto，可以得到 Post 对象。

Controller

先上Controller的代码

[Authorize]

[ApiController]

[Route("Api/[controller]")]

[ApiExplorerSettings(GroupName = "blog")]

public class BlogPostController : ControllerBase {

    private readonly IMapper _mapper;

    private readonly PostService _postService;

    private readonly BlogService _blogService;

    public BlogPostController(PostService postService, BlogService blogService, IMapper mapper) {

        _postService = postService;

        _blogService = blogService;

        _mapper = mapper;

    }

}

加在Controller上面的四个特性，挨个介绍

Authorize 表示这个controller下面的所有接口需要登录才能访问
ApiController 表示这是个WebApi Controller
Route 指定了这个Controller的路由模板，即下面的接口全是以 Api/BlogPostController 开头
ApiExplorerSettings 接口分组，在swagger文档里看会更清晰

接下来，添加和修改是俩接口，分开说。

添加

很容易，直接上代码了

[HttpPost]

public async Task<ApiResponse<Post>> Add(PostCreationDto dto, [FromServices] CategoryService categoryService) {

    // 使用 AutoMapper，前面介绍过的

    var post = _mapper.Map<Post>(dto);

    // 获取文章分类，如果不存在就返回报错信息

    var category = categoryService.GetById(dto.CategoryId);

    if (category == null) return ApiResponse.BadRequest($"分类 {dto.CategoryId} 不存在！");

    // 生成文章的ID、创建、更新时间

    post.Id = GuidUtils.GuidTo16String();

    post.CreationTime = DateTime.Now;

    post.LastUpdateTime = DateTime.Now;

    // 设置文章状态为已发布

    post.IsPublish = true;

    // 获取分类的层级结构

    post.Categories = categoryService.GetCategoryBreadcrumb(category);

    return new ApiResponse<Post>(await _postService.InsertOrUpdateAsync(post));

}

就是这个 Add 方法

目前 CategoryService 只需要在这个添加的接口里用到，所以不用整个Controller注入，在 Add 方法里使用 [FromServices] 特性注入。

后面有个获取分类的层级结构，因为StarBlog的设计是支持多级分类，为了在前台展示文章分类层级的时候减少运算量，所以我把文章的分类层级结构（形式是分类ID用逗号分隔开，如：1,3,5,7,9）直接存入数据库，空间换时间。

最后，执行 PostService 里的 InsertOrUpdateAsync 方法，解析处理文章内容，并将文章存入数据库。

PS：本项目的接口返回值已经做统一包装处理，可以看到大量使用 ApiResponse 作为返回值，这个后续文章会介绍。

修改

噢，还有 修改文章(Update) 的接口，修改使用 PUT 方法

[HttpPut("{id}")]

public async Task<ApiResponse<Post>> Update(string id, PostUpdateDto dto) {

    // 先获取文章对象

    var post = _postService.GetById(id);

    if (post == null) return ApiResponse.NotFound($"博客 {id} 不存在");

	// 在已有对象的基础上进行映射

    post = _mapper.Map(dto, post);

    // 更新修改时间

    post.LastUpdateTime = DateTime.Now;

    return new ApiResponse<Post>(await _postService.InsertOrUpdateAsync(post));

}

依然很简单，里面注释写得很清楚了

AutoMapper可以对已有对象的基础上进行映射

mapper.Map(source) 得到一个全新的对象
mapper.Map(source, dest) 在 dest 对象的基础上修改

搞定。

Service

作为一个多层架构项目，核心逻辑依然放在 Service 里

并且这里是添加和修改二合一，优雅~

public async Task<Post> InsertOrUpdateAsync(Post post) {

    var postId = post.Id;

    // 是新文章的话，先保存到数据库

    if (await _postRepo.Where(a => a.Id == postId).CountAsync() == 0) {

        post = await _postRepo.InsertAsync(post);

    }

    // 检查文章中的外部图片，下载并进行替换

    // todo 将外部图片下载放到异步任务中执行，以免保存文章的时候太慢

    post.Content = await MdExternalUrlDownloadAsync(post);

    // 修改文章时，将markdown中的图片地址替换成相对路径再保存

    post.Content = MdImageLinkConvert(post, false);

    // 处理完内容再更新一次

    await _postRepo.UpdateAsync(post);

    return post;

}

另外，这部分代码在之前的markdown渲染和自动下载外部图片的相关文章里已经介绍过了，本文不再重复。详情可以看本系列的第17篇文章。

删 (Delete)

没什么好说的，直接上代码

StarBlog.Web/Services/PostService.cs

public int Delete(string id) {

    return _postRepo.Delete(a => a.Id == id);

}

StarBlog.Web/Apis/Blog/BlogPostController.cs

[HttpDelete("{id}")]

public ApiResponse Delete(string id) {

    var post = _postService.GetById(id);

    if (post == null) return ApiResponse.NotFound($"博客 {id} 不存在");

    var rows = _postService.Delete(id);

    return ApiResponse.Ok($"删除了 {rows} 篇博客");

}

查 (Retrieve)

查，分成两种，一种是列表，一种是单个。

单个

先说单个的，比较容易。

StarBlog.Web/Services/PostService.cs

public Post? GetById(string id) {

    // 获取文章的时候对markdown中的图片地址解析，加上完整地址返回给前端

    var post = _postRepo.Where(a => a.Id == id).Include(a => a.Category).First();

    if (post != null) post.Content = MdImageLinkConvert(post, true);

    return post;

}

StarBlog.Web/Apis/Blog/BlogPostController.cs

[AllowAnonymous]

[HttpGet("{id}")]

public ApiResponse<Post> Get(string id) {

    var post = _postService.GetById(id);

    return post == null ? ApiResponse.NotFound() : new ApiResponse<Post>(post);

}

这里接口加了个 [AllowAnonymous]，表示这接口不用登录也能访问。

列表

列表有点麻烦，需要过滤筛选、排序、分页等功能，我打算把这些功能放到后面的文章讲，不然本文的篇幅就爆炸了…

那最简单的就是直接返回全部文章列表。

[HttpGet]

public List<Post> GetAll() {

    return _postService.GetAll();

}

够简单吧？

文章的相关操作

单纯的CRUD是无法满足功能需求的

所以要在RESTFul接口的接触上，配合一些RPC风格接口，实现我们需要的功能。

设置推荐文章

有一个模型专门管理推荐文章，名为 FeaturedPost

要设置推荐文章，直接往里面添加数据就行了。反之，取消就是删除对应的记录。

上代码

StarBlog.Web/Services/PostService.cs

public FeaturedPost AddFeaturedPost(Post post) {

    var item = _fPostRepo.Where(a => a.PostId == post.Id).First();

    if (item != null) return item;

    item = new FeaturedPost {PostId = post.Id};

    _fPostRepo.Insert(item);

    return item;

}

StarBlog.Web/Apis/Blog/BlogPostController.cs

[HttpPost("{id}/[action]")]

public ApiResponse<FeaturedPost> SetFeatured(string id) {

    var post = _postService.GetById(id);

    return post == null

        ? ApiResponse.NotFound()

        : new ApiResponse<FeaturedPost>(_blogService.AddFeaturedPost(post));

}

配置完URL就是：Api/BlogPost/{id}/SetFeatured 了

取消推荐文章

上面那个推荐的逆向操作

service这样写

public int DeleteFeaturedPost(Post post) {

    var item = _fPostRepo.Where(a => a.PostId == post.Id).First();

    return item == null ? 0 : _fPostRepo.Delete(item);

}

controller酱子

[HttpPost("{id}/[action]")]

public ApiResponse CancelFeatured(string id) {

    var post = _postService.GetById(id);

    if (post == null) return ApiResponse.NotFound($"博客 {id} 不存在");

    var rows = _blogService.DeleteFeaturedPost(post);

    return ApiResponse.Ok($"delete {rows} rows.");

}

设置置顶

StarBlog设计为只允许一篇置顶文章

设置新的置顶文章，会把原有的顶掉

service代码

/// <returns>返回 <see cref="TopPost"/> 对象和删除原有置顶博客的行数</returns>

public (TopPost, int) SetTopPost(Post post) {

    var rows = _topPostRepo.Select.ToDelete().ExecuteAffrows();

    var item = new TopPost {PostId = post.Id};

    _topPostRepo.Insert(item);

    return (item, rows);

}

先删除已有置顶文章，再添加新的进去。返回值用了元组语法。

controller代码

[HttpPost("{id}/[action]")]

public ApiResponse<TopPost> SetTop(string id) {

    var post = _postService.GetById(id);

    if (post == null) return ApiResponse.NotFound($"博客 {id} 不存在");

    var (data, rows) = _blogService.SetTopPost(post);

    return new ApiResponse<TopPost> {Data = data, Message = $"ok. deleted {rows} old topPosts."};

}

就这样，简简单单。

上传图片

场景：在后台编辑文章，会插入一些图片。

这个接口因为要上传文件，所以使用FormData接收参数，前端发起请求需要注意。

这是controller代码：

[HttpPost("{id}/[action]")]

public ApiResponse UploadImage(string id, IFormFile file) {

    var post = _postService.GetById(id);

    if (post == null) return ApiResponse.NotFound($"博客 {id} 不存在");

    var imgUrl = _postService.UploadImage(post, file);

    return ApiResponse.Ok(new {

        imgUrl,

        imgName = Path.GetFileNameWithoutExtension(imgUrl)

    });

}

后面的 PostService.UploadImage() 方法，本文(囿于篇幅关系)先不介绍了，留个坑，放在后面图片管理接口里一起介绍哈~

博客的相关操作

刚才基本是在对文章做CRUD，别忘了还有个 BlogController 呢~

功能就是获取推荐、获取置顶、博客文章总览、打包上传之类的。

这里也大概介绍一下。

获取推荐、置顶的service代码：

public List<Post> GetFeaturedPosts() {

    return _fPostRepo.Select.Include(a => a.Post.Category)

        .ToList(a => a.Post);

}

public Post? GetTopOnePost() {

    return _topPostRepo.Select.Include(a => a.Post.Category).First()?.Post;

}

controller太简单，就不写了。

总览信息

这里没封装到service里，感觉其他地方不会用到，拒绝过度封装。

直接从ORM读取，文章、分类、图片、推荐等的数量。

PS：要做展示大屏的话，这些应该还是不够的，后续再增加（flag立下了）

public BlogOverview Overview() {

    return new BlogOverview {

        PostsCount = _postRepo.Select.Count(),

        CategoriesCount = _categoryRepo.Select.Count(),

        PhotosCount = _photoRepo.Select.Count(),

        FeaturedPostsCount = _fPostRepo.Select.Count(),

        FeaturedCategoriesCount = _fCategoryRepo.Select.Count(),

        FeaturedPhotosCount = _fPhotoRepo.Select.Count()

    };

}

打包上传

这个功能是：把本地写完的markdown文件连同图片等资源一起打包zip上传，StarBlog解析markdown并将图片附件处理后存入数据库，实现很方便的本地写文章，博客发表功能。

具体实现已经在之前的文章里介绍过了，这里就不重复啦，详情可以查看本系列的第18篇文章。基于.NetCore开发博客项目 StarBlog - (18) 实现本地Typora文章打包上传

小结

AspNetCore WebApi的开发有很多东西可以写的，在开发过程中我也在不断学习，有很多好玩的新功能、骚操作是在后面才加入StarBlog项目的，但为了保证本系列文章阅读的连贯性，即使某功能在文章撰写时已经实现，也可能不会加入介绍。这些我会在后面单独写一篇文章来介绍(绝不是在水哦)，以提升读者的阅读体验。

还有，作为新手向教程，我会尽量写得比较详细（废话比较多），导致篇幅较长，但但仍无法面面俱到介绍AspNetCore的全部细节，建议边看边学的读者搭配AspNetCore官方文档或教材阅读~

系列文章