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

技术分享 2年前 (2022-12-19) 0 999+

关注

前言

本文介绍博客文章相关接口的开发，作为接口开发介绍的第一篇，会写得比较详细，以抛砖引玉，后面的其他接口就粗略带过了，着重于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官方文档或教材阅读~