部落格最基本的功能就是讓作者能夠自由釋出自己的文章,分享自己觀點,記錄學習的過程。Halo 為使用者提供了釋出文章和展示自定義頁面的功能,下面我們分析一下這些功能的實作過程。
基本介紹
部落格最基本的功能就是讓作者能夠自由釋出自己的文章,分享自己觀點,記錄學習的過程。Halo 為使用者提供了釋出文章和展示自定義頁面的功能,下面我們分析一下這些功能的實作過程。
管理者釋出文章
Halo 項目中,文章和頁面的實體類分别為 Post 和 Sheet,二者都是 BasePost 的子類。BasePost 對應資料庫中的 posts 表,posts 表既存儲了文章的資料,又存儲了頁面的資料,那麼項目中是如何區分文章和頁面的呢?下面是 BasePost 類的源碼(僅展示部分代碼):
@Data
@Entity(name = "BasePost")
@Table(name = "posts", indexes = {
@Index(name = "posts_type_status", columnList = "type, status"),
@Index(name = "posts_create_time", columnList = "create_time")})
@DiscriminatorColumn(name = "type", discriminatorType = DiscriminatorType.INTEGER,
columnDefinition = "int default 0")
@ToString(callSuper = true)
@EqualsAndHashCode(callSuper = true)
public class BasePost extends BaseEntity {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY, generator = "custom-id")
@GenericGenerator(name = "custom-id", strategy = "run.halo.app.model.entity.support"
+ ".CustomIdGenerator")
private Integer id;
/**
* Post title.
*/
@Column(name = "title", nullable = false)
private String title;
/**
* Post status.
*/
@Column(name = "status")
@ColumnDefault("1")
private PostStatus status;
// 此處省略部分代碼
}
我們知道,Halo 使用 JPA 來建立資料表、存儲和擷取表中的資訊。上述代碼中,注解 @DiscriminatorColumn 是之前文章中沒有介紹過的,@DiscriminatorColumn 屬于 JPA 注解,它的作用是當多個實體類對應同一個資料表時,可使用一個字段進行區分。name 指定該字段的名稱,discriminatorType 是該字段的類型,columnDefinition 設定該字段的預設值。由此可知,字段 type 是區分文章和頁面的依據,下面是 Post 類和 Sheet 類的源碼:
// Post
@Entity(name = "Post")
@DiscriminatorValue(value = "0")
public class Post extends BasePost {
}
// Sheet
@Entity(name = "Sheet")
@DiscriminatorValue("1")
public class Sheet extends BasePost {
}
Post 和 Sheet 都沒有定義額外的屬性,二者的差別僅在于注解 @DiscriminatorValue 設定的 value 不同。上文提到,@DiscriminatorColumn 指明了用作區分的字段,而 @DiscriminatorValue 的作用就是指明該字段的具體值。也就是說,type 為 0 時表示文章,為 1 時表示頁面。另外,這裡也簡單介紹一下 @Index 注解,該注解用于聲明表中的索引,例如 @Index(name = "posts_type_status", columnList = "type, status") 表示在 posts 表中建立 type 和 status 的複合索引,索引名稱為 posts_type_status。
下面我們繼續分析文章是如何釋出的,首先進入到管理者界面,然後點選 "文章" -> "寫文章",之後就可以填寫内容了:
![](https://img.laitimes.com/img/_0nNw4CM6IyYiwiM6ICdiwiIn5GcukTMyQjM4ETM30SOxYzMxIDM4EDMyQDMyIDMy0SNwYDMzQjMvwFNwIjMwIzLcVDM2AzM0IzLcd2bsJ2Lc12bj5ycn9Gbi52YuIjMwIzZtl2Lc9CX6MHc0RHaiojIsJye.png)
為了全面了解文章釋出的過程,我們盡量将能填的資訊都填上。點選 "釋出",觸發
/api/admin/posts
請求:
api/admin/posts
請求在 PostController 中定義:
@PostMapping
@ApiOperation("Creates a post")
public PostDetailVO createBy(@Valid @RequestBody PostParam postParam,
@RequestParam(value = "autoSave", required = false, defaultValue = "false") Boolean autoSave
) {
// 将 PostParam 對象轉化為 Post 對象
// Convert to
Post post = postParam.convertTo();
// 根據參數建立文章
return postService.createBy(post, postParam.getTagIds(), postParam.getCategoryIds(),
postParam.getPostMetas(), autoSave);
}
該請求接收兩個參數,即 postParam 和 autoSave。postParam 存儲我們填寫的文章資訊,autoSave 是與系統日志有關的參數,預設為 false。伺服器收到請求後,首先将接收到的 PostParam 對象轉化為 Post 對象,然後從 PostParam 中提取出文章标簽、分類、中繼資料等,接着調用 createBy 方法建立文章,createBy 方法的處理邏輯為:
public PostDetailVO createBy(Post postToCreate, Set<Integer> tagIds, Set<Integer> categoryIds,
Set<PostMeta> metas, boolean autoSave) {
// 建立或更新文章
PostDetailVO createdPost = createOrUpdate(postToCreate, tagIds, categoryIds, metas);
if (!autoSave) {
// 記錄系統日志
// Log the creation
LogEvent logEvent = new LogEvent(this, createdPost.getId().toString(),
LogType.POST_PUBLISHED, createdPost.getTitle());
eventPublisher.publishEvent(logEvent);
}
return createdPost;
}
該方法會調用 createOrUpdate 方法建立文章,由于 autoSave 為 false,是以文章建立完成後會記錄一條關于文章釋出的系統日志。繼續進入 createOrUpdate 方法,檢視建立文章的具體過程:
private PostDetailVO createOrUpdate(@NonNull Post post, Set<Integer> tagIds,
Set<Integer> categoryIds, Set<PostMeta> metas) {
Assert.notNull(post, "Post param must not be null");
// 檢視建立或更新的文章是否為私密文章
// Create or update post
Boolean needEncrypt = Optional.ofNullable(categoryIds)
.filter(HaloUtils::isNotEmpty)
.map(categoryIdSet -> {
for (Integer categoryId : categoryIdSet) {
// 文章分類是否設有密碼
if (categoryService.categoryHasEncrypt(categoryId)) {
return true;
}
}
return false;
}).orElse(Boolean.FALSE);
// 如果文章的密碼不為空或者所屬分類設有密碼, 那麼該文章就屬于私密文章
// if password is not empty or parent category has encrypt, change status to intimate
if (post.getStatus() != PostStatus.DRAFT
&& (StringUtils.isNotEmpty(post.getPassword()) || needEncrypt)
) {
post.setStatus(PostStatus.INTIMATE);
}
// 格式化文章的内容, 檢查文章的别名是否有重複, 都沒問題就建立文章
post = super.createOrUpdateBy(post);
// 移除文章原先綁定的标簽
postTagService.removeByPostId(post.getId());
// 移除文章原先綁定的分類
postCategoryService.removeByPostId(post.getId());
// 新設定的标簽
// List all tags
List<Tag> tags = tagService.listAllByIds(tagIds);
// 新設定的分類
// List all categories
List<Category> categories = categoryService.listAllByIds(categoryIds, true);
// Create post tags
List<PostTag> postTags = postTagService.mergeOrCreateByIfAbsent(post.getId(),
ServiceUtils.fetchProperty(tags, Tag::getId));
log.debug("Created post tags: [{}]", postTags);
// Create post categories
List<PostCategory> postCategories =
postCategoryService.mergeOrCreateByIfAbsent(post.getId(),
ServiceUtils.fetchProperty(categories, Category::getId));
log.debug("Created post categories: [{}]", postCategories);
// 移除文章原有的中繼資料并将新設定的中繼資料綁定到該文章
// Create post meta data
List<PostMeta> postMetaList = postMetaService
.createOrUpdateByPostId(post.getId(), metas);
log.debug("Created post metas: [{}]", postMetaList);
// 當文章建立或更新時清除對所有用戶端的授權
// Remove authorization every time an post is created or updated.
authorizationService.deletePostAuthorization(post.getId());
// 傳回文章的資訊, 便于管理者界面展示
// Convert to post detail vo
return convertTo(post, tags, categories, postMetaList);
}
- 檢查目前建立或更新的文章是否為私密文章,如果文章設有密碼,或者文章所屬的分類設有密碼,那麼就将文章的狀态改為 INTIMATE,表示該文章屬于私密文章。
- 對文章的内容進行格式化,也就是将原始内容轉化為能夠在前端展示的帶有 HTML 标簽的内容。然後檢查文章的别名是否有重複,檢查無誤後在 posts 表中建立該文章。
- 移除文章原先綁定的所有标簽和分類。
- 為文章重新綁定标簽和分類,以标簽為例,綁定的邏輯為:首先查詢出文章原先綁定的标簽,記為集合 A,然後将新設定的标簽記為集合 B,之後在 post_tags 表中删除集合 A 中存在但集合 B 中不存在的記錄,并建立集合 B 中不存在而集合 A 中存在的記錄。步驟 4 其實和步驟 3 是有沖突的,因為步驟 3 将文章原先綁定的标簽删除了,是以集合 A 中的元素總是為 0,實際上步驟 3 中的操作是多餘的,可以将其注釋掉。
- 移除文章原有的中繼資料,将新設定的中繼資料綁定到該文章。
- 删除對所有用戶端的文章授權,文章授權是針對私密文章設定的,在下節中我們會分析一下文章授權的作用。
- 傳回文章的具體資訊,供管理者頁面展示。
執行完以上步驟,一篇文章就建立或更新完成了:
使用者端通路文章
本節介紹使用者(普通使用者,非管理者)通路文章的具體過程,上文中,我們在建立文章時為文章設定了密碼,是以該文章屬于私密文章。Halo 為私密文章設定了的 "授權" 機制,授權指的是當使用者首次通路私密文章時,需要填寫通路密碼,伺服器收到請求後,會檢查使用者的密碼是否正确。如果正确,那麼服務端會對用戶端進行授權,這樣當使用者在短時間内再次通路該文章時可以不用重複輸入密碼。
預設情況下私密文章是不會在部落格首頁展示的,為了測試,我們修改 PostModel 中的 list 方法,首先将下面的代碼注釋掉:
Page<Post> postPage = postService.pageBy(PostStatus.PUBLISHED, pageable);
然後新增如下代碼:
PostQuery query = new PostQuery();
query.setStatuses(new HashSet<>(Arrays.asList(PostStatus.PUBLISHED, PostStatus.INTIMATE)));
Page<Post> postPage = postService.pageBy(query, pageable);
這樣,部落格首頁就可以展示狀态為 "已釋出" 和 "私密" 的文章了:
點選 "我的第一篇文章",觸發
/archives/first
請求,first 為文章的别名 slug,該請求由 ContentContentController 的 content 方法處理(僅展示部分代碼):
@GetMapping("{prefix}/{slug}")
public String content(@PathVariable("prefix") String prefix,
@PathVariable("slug") String slug,
@RequestParam(value = "token", required = false) String token,
Model model) {
PostPermalinkType postPermalinkType = optionService.getPostPermalinkType();
if (optionService.getArchivesPrefix().equals(prefix)) {
if (postPermalinkType.equals(PostPermalinkType.DEFAULT)) {
// 根據 slug 查詢出文章的
Post post = postService.getBySlug(slug);
return postModel.content(post, token, model);
}
// 省略部分代碼
}
}
上述方法首先根據 slug 查詢出 title 為 "我的第一篇文章" 的文章,然後調用 postModel.content 方法封裝文章的資訊,postModel.content 方法的處理邏輯如下:
public String content(Post post, String token, Model model) {
// 文章在資源回收筒
if (PostStatus.RECYCLE.equals(post.getStatus())) {
// Articles in the recycle bin are not allowed to be accessed.
throw new NotFoundException("查詢不到該文章的資訊");
} else if (StringUtils.isNotBlank(token)) {
// If the token is not empty, it means it is an admin request,
// then verify the token.
// verify token
String cachedToken = cacheStore.getAny(token, String.class)
.orElseThrow(() -> new ForbiddenException("您沒有該文章的通路權限"));
if (!cachedToken.equals(token)) {
throw new ForbiddenException("您沒有該文章的通路權限");
}
// 手稿
} else if (PostStatus.DRAFT.equals(post.getStatus())) {
// Drafts are not allowed bo be accessed by outsiders.
throw new NotFoundException("查詢不到該文章的資訊");
//
} else if (PostStatus.INTIMATE.equals(post.getStatus())
&& !authenticationService.postAuthentication(post, null)
) {
// Encrypted articles must has the correct password before they can be accessed.
model.addAttribute("slug", post.getSlug());
model.addAttribute("type", EncryptTypeEnum.POST.getName());
// 如果激活的主題定義了輸入密碼頁面
if (themeService.templateExists(POST_PASSWORD_TEMPLATE + SUFFIX_FTL)) {
return themeService.render(POST_PASSWORD_TEMPLATE);
}
// 進入輸入密碼頁面
return "common/template/" + POST_PASSWORD_TEMPLATE;
}
post = postService.getById(post.getId());
if (post.getEditorType().equals(PostEditorType.MARKDOWN)) {
post.setFormatContent(MarkdownUtils.renderHtml(post.getOriginalContent()));
} else {
post.setFormatContent(post.getOriginalContent());
}
postService.publishVisitEvent(post.getId());
postService.getPrevPost(post).ifPresent(
prevPost -> model.addAttribute("prevPost", postService.convertToDetailVo(prevPost)));
postService.getNextPost(post).ifPresent(
nextPost -> model.addAttribute("nextPost", postService.convertToDetailVo(nextPost)));
List<Category> categories = postCategoryService.listCategoriesBy(post.getId(), false);
List<Tag> tags = postTagService.listTagsBy(post.getId());
List<PostMeta> metas = postMetaService.listBy(post.getId());
// Generate meta keywords.
if (StringUtils.isNotEmpty(post.getMetaKeywords())) {
model.addAttribute("meta_keywords", post.getMetaKeywords());
} else {
model.addAttribute("meta_keywords",
tags.stream().map(Tag::getName).collect(Collectors.joining(",")));
}
// Generate meta description.
if (StringUtils.isNotEmpty(post.getMetaDescription())) {
model.addAttribute("meta_description", post.getMetaDescription());
} else {
model.addAttribute("meta_description",
postService.generateDescription(post.getFormatContent()));
}
model.addAttribute("is_post", true);
model.addAttribute("post", postService.convertToDetailVo(post));
model.addAttribute("categories", categoryService.convertTo(categories));
model.addAttribute("tags", tagService.convertTo(tags));
model.addAttribute("metas", postMetaService.convertToMap(metas));
if (themeService.templateExists(
ThemeService.CUSTOM_POST_PREFIX + post.getTemplate() + SUFFIX_FTL)) {
return themeService.render(ThemeService.CUSTOM_POST_PREFIX + post.getTemplate());
}
return themeService.render("post");
}
- 如果文章狀态為 "草稿" 或 "位于資源回收筒",那麼向前端回報無文章資訊。如果請求的 Query 中存在 token,那麼該請求為一個 admin 請求(與管理者在背景浏覽文章時發送的請求是類似的,隻不過在管理者界面通路文章時 token 存儲在請求的 Header 中,這裡的 token 存儲在請求的 Query 參數中),此時檢查 token 是否有效。如果文章狀态為 "私密" 且用戶端并未獲得 "授權",那麼重定向到密碼輸入頁面,否則執行如下步驟。
- 對文章内容進行格式化,記錄文章被通路的系統日志。
- 在 model 中封裝文章的内容、标簽、分類、中繼資料、前一篇文章、後一篇文章等資訊,然後利用 FreeMaker 基于 post.ftl 檔案(已激活主題的)生成 HTML 頁面。
對于 "已釋出" 和 "已獲得授權" 的文章,請求處理完成後使用者可直接看到文章的内容。由于 "我的第一篇文章" 屬于私密文章且并未對使用者進行授權,是以頁面發生了重定向:
輸入密碼後,點選 "驗證",觸發
content/post/first/authentication
請求,該請求由 ContentContentController 的 password 方法處理:
@PostMapping(value = "content/{type}/{slug:.*}/authentication")
@CacheLock(traceRequest = true, expired = 2)
public String password(@PathVariable("type") String type,
@PathVariable("slug") String slug,
@RequestParam(value = "password") String password) throws UnsupportedEncodingException {
String redirectUrl;
// 如果 type 為 post
if (EncryptTypeEnum.POST.getName().equals(type)) {
// 授權操作
redirectUrl = doAuthenticationPost(slug, password);
} else if (EncryptTypeEnum.CATEGORY.getName().equals(type)) {
redirectUrl = doAuthenticationCategory(slug, password);
} else {
throw new UnsupportedException("未知的加密類型");
}
return "redirect:" + redirectUrl;
}
因為 URL 中的 type 為 post(我們通路的是文章),是以由 doAuthenticationPost 方法為用戶端授權:
private String doAuthenticationPost(
String slug, String password) throws UnsupportedEncodingException {
Post post = postService.getBy(PostStatus.INTIMATE, slug);
post.setSlug(URLEncoder.encode(post.getSlug(), StandardCharsets.UTF_8.name()));
authenticationService.postAuthentication(post, password);
BasePostMinimalDTO postMinimalDTO = postService.convertToMinimal(post);
StringBuilder redirectUrl = new StringBuilder();
if (!optionService.isEnabledAbsolutePath()) {
redirectUrl.append(optionService.getBlogBaseUrl());
}
redirectUrl.append(postMinimalDTO.getFullPath());
return redirectUrl.toString();
}
上述代碼中,
authenticationService.postAuthentication(post, password);
是為用戶端進行授權操作的,授權完成後伺服器會将請求重定向到
/archives/first
,如果授權成功那麼使用者就可以看到文章的内容,如果授權失敗那麼仍然處于 "密碼輸入" 頁面。進入到 postAuthentication 方法檢視授權的具體過程(省略部分代碼):
public boolean postAuthentication(Post post, String password) {
// 從 cacheStore 中查詢出目前用戶端已獲得授權的文章 id
Set<String> accessPermissionStore = authorizationService.getAccessPermissionStore();
// 如果文章的密碼不為空
if (StringUtils.isNotBlank(post.getPassword())) {
// 如果已經受過權
if (accessPermissionStore.contains(AuthorizationService.buildPostToken(post.getId()))) {
return true;
}
// 如果密碼正确就為用戶端授權
if (post.getPassword().equals(password)) {
authorizationService.postAuthorization(post.getId());
return true;
}
return false;
}
// 省略部分代碼
}
- 首先利用 cacheStore 查詢出目前用戶端已獲得授權的文章 id,cacheStore 是一個以 ConcurrentHashMap 為容器的内部緩存,該操作指的是從緩存中查詢出 key 為 "ACCESS_PERMISSION: sessionId" 的 value(一個 Set 集合),其中 sessionId 是目前 session 的 id。我們在前一篇文章中介紹過 Halo 中的 3 個過濾器,使用者端(非管理者)發送的浏覽文章的請求會被 ContentFilter 攔截,且每次攔截後都會執行 doAuthenticate 方法,該方法中的
保證了服務端一定會建立一個 session。session 建立完成後存儲在服務端,預設情況下服務端會為用戶端配置設定一個特殊的 cookie,名稱為 "JSESSIONID",其存儲的值就是 session 的 id。之後用戶端發送請求時,服務端可以通過請求中的 cookie 查詢出存儲的 session,并根據 session 确定用戶端的身份。是以可以使用 "ACCESS_PERMISSION: sessionId" 作為 key 來儲存目前用戶端已獲得授權的文章 id。request.getSession(true);
- 判斷文章的密碼是否為空,不為空就表示文章本身屬于私密文章,為空表示文章屬于設有密碼的分類。因為文章設有密碼,是以繼續執行下面的步驟。
- 檢視 accessPermissionStore 中(步驟 1 查詢出的 Set 集合)是否包含正在通路的文章的 id。如果包含,那麼就表示已為目前用戶端授權過,不包含的話繼續執行下面的步驟。
- 判斷使用者輸入的密碼與文章的密碼是否相同,相同的話就為用戶端授權,也就是在 accessPermissionStore 中存儲目前文章的 id。
授權成功後,用戶端再次通路該私密文章時,伺服器可以根據 cookie 得到 sessionId,然後從 cacheStore 中查詢出 key 為 "ACCESS_PERMISSION: sessionId" 的 value,判斷 value 中是否包含目前文章的 id。如果包含,那麼就表示用戶端已經獲得了文章的通路權限,伺服器可向前端傳回文章内容,這個過程對應的是前文中 postModel.content 方法的處理邏輯。
了解了 Halo 中的 "文章授權" 機制後,我們就能明白為什麼伺服器在建立或更新文章時會删除對所有用戶端的授權。因為此時文章的資訊發生了變化,密碼也可能重置,是以用戶端需要重新輸入密碼。結合前一篇文章我們可以得出結論:管理者通路管理者界面上的功能時,伺服器根據 Request Headers 中的 token 來确定管理者的身份。普通使用者通路私密文章時,伺服器根據 cookie 判斷使用者是否具有文章的通路權限,cookie 和 token 是兩種非常重要的身份認證方式。
用戶端(浏覽器)儲存的cookie:
用戶端通路文章時請求中攜帶 cookie:
中繼資料
中繼資料指的是描述資料屬性的資訊,Halo 中可為文章設定中繼資料。建立或更新文章時,點選 "進階" 選項後即可添加中繼資料,預設的主題
caicai_anatole
沒有提供可使用的中繼資料,是以我們将更主題更換為
joe2.0
(其它主題也可),為文章添加中繼資料:
上圖中,我們為 "我的第一篇文章" 添加了一個中繼資料,其中 meta_key 為 "enable_like",meta_value 為 "false",表示該文章不允許點贊。前文中介紹過,使用者通路文章時,伺服器會将文章的資訊進行封裝,其中就包括文章的中繼資料,封裝完成後,由 FreeMaker 基于 post.ftl 檔案生成用于浏覽的 HTML 頁面。
joe2.0
主題的 post.ftl 檔案會根據 "enable_like" 的值決定是否顯示點贊按鈕。
文章 "Hello Halo" 可以點贊:
"我的第一篇文章" 不可以點贊:
除了 "enable_like",還可以設定文章是否支援 mathjax 以及設定文章中圖檔的寬度等。
自定義頁面
Halo 中除文章外,部落客還可以對外分享自定義的頁面,例如部落格首頁的 "關于頁面" 就是系統在初始化部落格時為我們建立的頁面。頁面和文章的建立、檢視等操作是相似的,是以代碼的具體執行過程就不再介紹了。頁面建立完成後,在管理者界面的依次點選 "外觀" -> "菜單" -> "其他" -> "從系統預設連結添加" -> "自定義頁面" -> "添加" 即可在部落格首頁完成頁面的展示: