Halo 開源專案學習（五）：評論與點贊

基本介紹

部落格系統中，使用者瀏覽文章時可以在文章下方發表自己的觀點，與博主或其他使用者進行互動，也可以為喜歡的文章點贊。下面我們一起分析一下 Halo 專案中評論和點贊功能的實現過程。

發表評論

評論可以是對文章的評論，對頁面的評論，也可以是對評論的評論（通常稱為回覆），因此專案中需要對評論的類別進行劃分。評論的實體類 BaseComment 中設定了幾個重要的屬性：type、postId、parentId。其中 type 用於區分文章和頁面，type 為 0 表示對文章的評論，為 1 表示對頁面的評論；postId 用於指定評論屬於哪一篇文章或頁面；parentId 表示當前評論的 "父評論"，如果當前評論是對某個 "父評論" 的回覆，那麼 parentId 為該 "父評論" 的 id，如果評論文章，那麼 parentId 為 0。

進入部落格首頁，點開一篇文章，在下方發表評論：

點選 "評論" 按鈕後，觸發 api/content/posts/comments 請求：

該請求由 PostController 中的 comment 方法處理：

@PostMapping("comments")
@ApiOperation("Comments a post")
@CacheLock(autoDelete = false, traceRequest = true)
public BaseCommentDTO comment(@RequestBody PostCommentParam postCommentParam) {
    // 驗證當前 IP 是否處於封禁狀態
    postCommentService.validateCommentBlackListStatus();

    // 對評論的內容進行轉義
    // Escape content
    postCommentParam.setContent(HtmlUtils
        .htmlEscape(postCommentParam.getContent(), StandardCharsets.UTF_8.displayName()));
    // 建立評論
    return postCommentService.convertTo(postCommentService.createBy(postCommentParam));
}

comment 方法首先會檢查當前傳送評論的 IP 是否處於封禁狀態，如果未處於封禁狀態，那麼系統會對評論的內容進行 HTML 轉義，轉義完成後建立該評論。首先介紹一下 Halo 的 "封禁評論" 機制，封禁的目的是防止惡意 IP 搶佔和浪費部落格系統的資源。進入 validateCommentBlackListStatus 方法，檢視驗證 IP 的具體過程：

public void validateCommentBlackListStatus() {
    // 檢視當前 IP 的封禁狀態
    CommentViolationTypeEnum banStatus =
        commentBlackListService.commentsBanStatus(ServletUtils.getRequestIp());
    // 獲取系統設定的封禁時間
    Integer banTime = optionService
        .getByPropertyOrDefault(CommentProperties.COMMENT_BAN_TIME, Integer.class, 10);
    // 如果當前 IP 處於封禁狀態, 提示使用者稍後重試
    if (banStatus == CommentViolationTypeEnum.FREQUENTLY) {
        throw new ForbiddenException(String.format("您的評論過於頻繁，請%s分鐘之後再試。", banTime));
    }
}

上述程式碼中，伺服器首先查詢當前 IP 的封禁狀態，如果狀態為 FREQUENTLY，那麼就認為當前 IP 的評論過於頻繁，然後提示使用者稍後重試。該過程是一種 "限流" 機制，其重點在於如何設計 "頻繁評論" 的評判標準，直白一點就是如何 "限流"？限流的方式有很多種，如利用快取或記憶體佇列等。Halo 中使用資料庫來實現限流策略，這個設計思路也是非常值得學習的，commentsBanStatus 方法的處理邏輯如下：

public CommentViolationTypeEnum commentsBanStatus(String ipAddress) {
    /*
    N=後期可配置
    1. 獲取評論次數；
    2. 判斷N分鐘內，是否超過規定的次數限制，超過後需要每隔N分鐘才能再次評論；
    3. 如果在時隔N分鐘內，還有多次評論，可被認定為惡意攻擊者；
    4. 對惡意攻擊者進行N分鐘的封禁；
    */
    // 傳送評論的 ip 在封禁是否在封禁名單中
    Optional<CommentBlackList> blackList =
        commentBlackListRepository.findByIpAddress(ipAddress);
    LocalDateTime now = LocalDateTime.now();
    Date endTime = new Date(DateTimeUtils.toEpochMilli(now));
    // 封禁的時間間隔, 也是評估是否需要封禁的時間間隔, 預設 10 分鐘
    Integer banTime = optionService
        .getByPropertyOrDefault(CommentProperties.COMMENT_BAN_TIME, Integer.class, 10);
    // now - 時間間隔
    Date startTime = new Date(DateTimeUtils.toEpochMilli(now.minusMinutes(banTime)));
    // 評論數閾值, 預設為 30 個
    Integer range = optionService
        .getByPropertyOrDefault(CommentProperties.COMMENT_RANGE, Integer.class, 30);
    // 指定時間間隔內, 當前 ip 的評論數是否超過評論數閾值
    boolean isPresent =
        postCommentRepository.countByIpAndTime(ipAddress, startTime, endTime) >= range;
    if (isPresent && blackList.isPresent()) {
        // 設定當前 IP 的解禁時間為 banTime 分鐘後
        update(now, blackList.get(), banTime);
        return CommentViolationTypeEnum.FREQUENTLY;
    } else if (isPresent) {
        // 構建 CommentBlackList 物件, 設定當前 IP 的解禁時間為 banTime 分鐘後
        CommentBlackList commentBlackList = CommentBlackList
            .builder()
            .banTime(getBanTime(now, banTime))
            .ipAddress(ipAddress)
            .build();
        super.create(commentBlackList);
        return CommentViolationTypeEnum.FREQUENTLY;
    }
    return CommentViolationTypeEnum.NORMAL;
}

1. 查詢當前 IP 是否處於封禁黑名單（comment_black_list 表）中。

2. 查詢系統設定的時間閾值 banTime（預設是 10 分鐘），並判斷從 banTime 分鐘前到現在，當前 IP 的評論數是否超過了評論數閾值 range（預設是 30 個），如果超過了，那麼就需要對當前 IP 實施封禁措施。換句話說，如果 banTime 分鐘內，當前 IP 的評論數達到指定閾值，就對當前 IP 進行限流，這裡 banTime 是評估封禁的引數，也可以稱為時間閾值。

3. 達到限流條件後，如果當前 IP 存在於封禁黑名單，那麼更新 comment_black_list 表，將其解禁時間設定為 banTime 分鐘後，雖然 comment_black_list 表中的屬性 ban_time 在專案中被稱為封禁時間，但結合程式碼可以發現它的真實含義是解禁時間。如果當前 IP 不在封禁黑名單，那麼建立一條新的記錄，IP 為當前請求的 IP，解禁時間為 banTime 分鐘後。實際上，封禁黑名單的業務含義設定的並不嚴謹，它的作用僅僅是在資料表中建立或更新一條記錄，且記錄的解禁時間也只是一個參考值，因為評估 "限流" 的依據是 banTime 分鐘前到現在的總評論數，與黑名單中的時間並無關聯。Halo 中的 "限流" 機制類似於一個優先佇列，佇列的容量為 range，元素的屬性包括 IP 和入隊時間，如果元素入隊的時間與當前時間的間隔達到 banTime，那麼該元素出隊，如果佇列已滿，那麼實施 "限流"，一旦佇列恢復出至少一個空閒位置，那麼使用者便可再次發表評論。

4. 達到限流條件後返回封禁狀態 FREQUENTLY，否則返回 NORMAL。

瞭解了封禁機制後，我們再說一說 HTML 轉義，轉義指的是對一些特殊的標籤，如 <、>、& 等進行轉義，使系統認為其屬於普通的符號，不具備標籤功能。HTML 內容轉義可以有效防止 XSS 攻擊，HtmlUtils 工具類中的 htmlEscape 方法可實現轉義操作。

接下來，我們來分析評論的建立過程，即 createBy 方法的處理邏輯：

public COMMENT createBy(@NonNull BaseCommentParam<COMMENT> commentParam) {
    Assert.notNull(commentParam, "Comment param must not be null");

    // Check user login status and set this field
    Authentication authentication = SecurityContextHolder.getContext().getAuthentication();

    // 博主的評論
    if (authentication != null) {
        // Blogger comment
        User user = authentication.getDetail().getUser();
        commentParam.setAuthor(
            StringUtils.isBlank(user.getNickname()) ? user.getUsername() : user.getNickname());
        commentParam.setEmail(user.getEmail());
        commentParam.setAuthorUrl(
            optionService.getByPropertyOrDefault(BlogProperties.BLOG_URL, String.class, null));
    }

    // Validate the comment param manually
    ValidationUtils.validate(commentParam);
    // 普通使用者的評論
    if (authentication == null) {
        // Anonymous comment
        // Check email
        if (userService.getByEmail(commentParam.getEmail()).isPresent()) {
            throw new BadRequestException("不能使用博主的郵箱，如果您是博主，請登入管理端進行回覆。");
        }
    }

    // Convert to comment
    return create(commentParam.convertTo());
}

1. 從 ThreadLocal 容器中獲取使用者資訊，如果使用者資訊不為空，那麼當前發表評論的使用者為博主，因為普通使用者是不需要登入的，確認博主身份後在 commentParam 引數中封裝博主的資訊。

2. 校驗 commentParam 引數是否符合 BaseCommentParam 類中制定的規則，例如評論者的暱稱不能為空，郵箱格式必須正確等。

3. 如果步驟 1 中使用者資訊為空，那麼當前評論來自於普通使用者。許多部落格系統對普通使用者的資訊並沒有太嚴格的要求，比如 Halo 中使用者發表評論時只需要填寫暱稱和郵箱，但需要注意普通使用者的郵箱不能和管理員的郵箱重複。

上述步驟中的驗證操作通過後，執行 create 方法建立評論：

public COMMENT create(@NonNull COMMENT comment) {
    Assert.notNull(comment, "Domain must not be null");

    // 確保文章是存在的
    // Check post id
    if (!ServiceUtils.isEmptyId(comment.getPostId())) {
        validateTarget(comment.getPostId());
    }

    // 如果 parentId 是非 0 的整數, 那麼該評論為使用者的回覆, 該評論的 "父評論" 必須存在
    // Check parent id
    if (!ServiceUtils.isEmptyId(comment.getParentId())) {
        mustExistById(comment.getParentId());
    }

    // Check user login status and set this field
    final Authentication authentication =
        SecurityContextHolder.getContext().getAuthentication();

    // 設定預設值
    // Set some default values
    if (comment.getIpAddress() == null) {
        comment.setIpAddress(ServletUtils.getRequestIp());
    }

    // 設定 useragent
    if (comment.getUserAgent() == null) {
        comment.setUserAgent(ServletUtils.getHeaderIgnoreCase(HttpHeaders.USER_AGENT));
    }
    // 設定頭像
    if (comment.getGravatarMd5() == null) {
        comment.setGravatarMd5(
            DigestUtils.md5Hex(Optional.ofNullable(comment.getEmail()).orElse("")));
    }

    // 將使用者設定的 URL 規範化
    if (StringUtils.isNotEmpty(comment.getAuthorUrl())) {
        comment.setAuthorUrl(HaloUtils.normalizeUrl(comment.getAuthorUrl()));
    }
    // 來自於博主的評論, 評論狀態直接為 PUBLISHED
    if (authentication != null) {
        // Comment of blogger
        comment.setIsAdmin(true);
        comment.setStatus(CommentStatus.PUBLISHED);
    } else {
        // Comment of guest
        // Handle comment status
        // 如果設定了評論稽核, 需要將評論狀態先設定為待稽核狀態
        Boolean needAudit = optionService
            .getByPropertyOrDefault(CommentProperties.NEW_NEED_CHECK, Boolean.class, true);
        comment.setStatus(needAudit ? CommentStatus.AUDITING : CommentStatus.PUBLISHED);
    }
    // 建立評論
    // Create comment
    COMMENT createdComment = super.create(comment);

    // 如果 parentId 為 0, 表示該評論是對文章的評論
    if (ServiceUtils.isEmptyId(createdComment.getParentId())) {
        if (authentication == null) {
            // 新增評論事件
            // New comment of guest
            eventPublisher.publishEvent(new CommentNewEvent(this, createdComment.getId()));
        }
    } else {
        // 回覆評論事件
        // Reply comment
        eventPublisher.publishEvent(new CommentReplyEvent(this, createdComment.getId()));
    }

    return createdComment;
}

1. 首先確保評論的合理性，即評論所屬的文章必須存在，如果評論的 parentId 是非 0 的整數，那麼該評論為使用者的回覆，該評論的 "父評論" 必須存在。

2. 為評論的 ipAddress、useragent、頭像設定預設值（如果為空），並對使用者設定的 URL 做規範化處理。

3. 如果評論來自於博主，那麼將 isAdmin 設定為 true，並將評論的狀態直接設定為 PUBLISHED。如果評論來自於普通使用者且系統開啟了稽核機制，那麼將評論的狀態設定為待稽核狀態 AUDITING，處於 AUDITING 狀態的評論需要博主稽核通過後才能顯示。

4. 在 comments 表中建立評論，併發布相應的事件。如果評論的 parentId 為 0（該評論是對文章的評論）且該評論來自於普通使用者，那麼釋出 "新增評論" 事件。如果 parentId 不為 0，釋出 "回覆評論" 事件。

create 方法執行成功後，一條評論就建立完成了 (^～^)!

檢視評論

我們在瀏覽文章時，可以看到文章底下使用者的評論，其中排在前面的通常是一些高贊評論（神回覆）或最新評論。如果評論數量較多，那麼部分評論可能會被摺疊，例如開啟一篇文章：

上圖中，我們只能看到文章的 "直系" 評論（對該文章的評論），而看不到對評論的評論。當文章被點開時，前端不僅會傳送 archives/{slug} 請求來獲取文章的具體內容，還會傳送 api/content/posts/{postId}/comments/top_view 請求來獲取屬於該文章的 "直系" 評論，該請求由 PostController 中的 listTopComments 方法處理：

@GetMapping("{postId:\\d+}/comments/top_view")
public Page<CommentWithHasChildrenVO> listTopComments(@PathVariable("postId") Integer postId,
    @RequestParam(name = "page", required = false, defaultValue = "0") int page,
    @SortDefault(sort = "createTime", direction = DESC) Sort sort) {
    return postCommentService.pageTopCommentsBy(postId, CommentStatus.PUBLISHED,
        PageRequest.of(page, optionService.getCommentPageSize(), sort));
}

"Top comments" 指的就是 "直系" 評論，進入 pageTopCommentsBy 方法，檢視列舉 Top comments 的具體過程：

public Page<CommentWithHasChildrenVO> pageTopCommentsBy(@NonNull Integer targetId,
    @NonNull CommentStatus status,
    @NonNull Pageable pageable) {
    Assert.notNull(targetId, "Target id must not be null");
    Assert.notNull(status, "Comment status must not be null");
    Assert.notNull(pageable, "Page info must not be null");

    // 根據 postId、status、parentId 查詢出所有 "直系" 評論, 非回覆
    // Get all comments
    Page<COMMENT> topCommentPage = baseCommentRepository
        .findAllByPostIdAndStatusAndParentId(targetId, status, 0L, pageable);

    if (topCommentPage.isEmpty()) {
        // If the comments is empty
        return ServiceUtils.buildEmptyPageImpl(topCommentPage);
    }

    // 獲取 "直系" 評論的 id 集合
    // Get top comment ids
    Set<Long> topCommentIds =
        ServiceUtils.fetchProperty(topCommentPage.getContent(), BaseComment::getId);
    // 獲取每一條 "直系" 評論的子評論數
    // Get direct children count
    List<CommentChildrenCountProjection> directChildrenCount =
        baseCommentRepository.findDirectChildrenCount(topCommentIds, CommentStatus.PUBLISHED);
    // map 的 key 是 "直系" 評論的 id, value 是對應的子評論數
    // Convert to comment - children count map
    Map<Long, Long> commentChildrenCountMap = ServiceUtils
        .convertToMap(directChildrenCount, CommentChildrenCountProjection::getCommentId,
            CommentChildrenCountProjection::getDirectChildrenCount);

    // Convert to comment with has children vo
    return topCommentPage.map(topComment -> {
        CommentWithHasChildrenVO comment =
            new CommentWithHasChildrenVO().convertFrom(topComment);
        comment
            .setHasChildren(commentChildrenCountMap.getOrDefault(topComment.getId(), 0L) > 0);
        comment.setAvatar(buildAvatarUrl(topComment.getGravatarMd5()));
        return comment;
    });
}

1. 首先根據 postId、status、parentId 查詢出所有 "直系" 評論，如果為空，那麼直接返回空的 Page，否則執行下面的步驟。

2. 將所有 "直系" 評論的 id 封裝在 Set 集合中，並獲取每一條評論的子評論數，之後構造 Map，其中 key 為 "直系" 評論的 id，value 為對應的子評論數。

3. 利用 CommentWithHasChildrenVO 封裝每一條評論的內容，並判斷評論是否包含子評論（如果包含子評論，前端頁面會顯示 "更多" 按鈕），最後設定頭像資訊。

通過上述操作可以檢視到使用者對文章的評論，如果希望看到對評論的回覆，則需要點選 "更多" 按鈕，此時前端傳送 api/content/posts/{postId}/comments/{commentParentId}/children 請求，該請求由 PostController 中的 listChildrenBy 方法處理：

@GetMapping("{postId:\\d+}/comments/{commentParentId:\\d+}/children")
public List<BaseCommentDTO> listChildrenBy(@PathVariable("postId") Integer postId,
    @PathVariable("commentParentId") Long commentParentId,
    @SortDefault(sort = "createTime", direction = DESC) Sort sort) {
    // Find all children comments
    List<PostComment> postComments = postCommentService
        .listChildrenBy(postId, commentParentId, CommentStatus.PUBLISHED, sort);
    // Convert to base comment dto

    return postCommentService.convertTo(postComments);
}

上述方法中，parentId 為某一條 "直系" 評論的 id，此 id 是一個大於 0 的整數，方法會返回該 "直系" 評論下狀態為 PUBLISHED 的所有子評論。下面我們進入 service 層中的 listChildrenBy 方法，檢視具體的邏輯：

public List<COMMENT> listChildrenBy(@NonNull Integer targetId, @NonNull Long commentParentId,
    @NonNull CommentStatus status, @NonNull Sort sort) {
    Assert.notNull(targetId, "Target id must not be null");
    Assert.notNull(commentParentId, "Comment parent id must not be null");
    Assert.notNull(sort, "Sort info must not be null");

    // Get comments recursively

    // 獲取 "直系" 評論的回覆
    // Get direct children
    List<COMMENT> directChildren = baseCommentRepository
        .findAllByPostIdAndStatusAndParentId(targetId, status, commentParentId);

    // Create result container
    Set<COMMENT> children = new HashSet<>();
    // 遞迴獲取 "直系" 評論的回覆的回覆
    // Get children comments
    getChildrenRecursively(directChildren, status, children);

    // Sort children
    List<COMMENT> childrenList = new ArrayList<>(children);
    // 對結果進行排序, 按照 commentId 升序排
    childrenList.sort(Comparator.comparing(BaseComment::getId));

    return childrenList;
}

1. 首先獲取 "直系" 評論的回覆，為了便於表述，我們將 "直系" 評論稱為一級評論，那麼 "直系" 評論的回覆就稱為二級評論，以此類推。

2. 由於二級評論下方也可能會有回覆，即三級評論，因此需要遞迴獲取所有的子評論。

3. 獲取到子評論後將所有的評論按照 id 升序排列並返回。

實際上在許多網站中，屬於文章的評論（"直系" 評論）和屬於評論的評論確實會做一個分級展示，但評論的評論之間一般是並列展示的：

上圖中，"直系" 評論下方有兩條子評論，其中子評論 2（"好的"）是對子評論 1（"收到"）的回覆，二者在前端的排版上屬於同一級，但為了更好地理清其中的邏輯關係，我們將其分為 "二級" 和 "三級"。下面檢視遞迴方法 getChildrenRecursively 查詢不同級別評論的過程：

private void getChildrenRecursively(@Nullable List<COMMENT> topComments,
    @NonNull CommentStatus status, @NonNull Set<COMMENT> children) {
    Assert.notNull(status, "Comment status must not be null");
    Assert.notNull(children, "Children comment set must not be null");

    if (CollectionUtils.isEmpty(topComments)) {
        return;
    }
    // 當前級別評論的 id 集合
    // Convert comment id set
    Set<Long> commentIds = ServiceUtils.fetchProperty(topComments, COMMENT::getId);
    // 獲取下一級評論
    // Get direct children
    List<COMMENT> directChildren =
        baseCommentRepository.findAllByStatusAndParentIdIn(status, commentIds);
    // 獲取下下一級評論
    // Recursively invoke
    getChildrenRecursively(directChildren, status, children);
    // 將評論封裝在 Set 集合中
    // Add direct children to children result
    children.addAll(topComments);
}

1. 首先獲取當前級別評論的 id 集合，並根據 id 集合從資料庫中獲取下一級評論。

2. 執行遞迴方法，根據下一級評論獲取下下級評論。

3. 將當前級別的評論存入到 Set 集合。

以上便是使用者瀏覽評論時後臺伺服器的處理流程。

評論的通知

Halo 中設定了評論通知的功能，當使用者傳送評論時，系統會傳送郵件通知博主。當博主回覆使用者的評論時，如果使用者設定的 Email 是有效的郵箱，那麼博主回覆的內容也會被髮送到使用者的郵箱中。下面以 QQ 郵箱為例，介紹一下操作過程。

首先進入 QQ 郵箱，點選左上角的 "設定"，選擇 "賬戶"。向下拉，找到 "POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV服務"，開啟 "POP3/SMTP服務"：

然後點選生成授權碼，使用密保手機傳送指定簡訊後就可以收到授權碼。接著進入 Halo 的管理員介面，點選 "系統" -> "部落格設定"，選擇 "SMTP 服務" 並填寫資訊，郵箱賬號填寫自己的 QQ 郵箱，密碼是生成的授權碼：

填寫完成後點選儲存，在右側的 "傳送測試" 選項中測試是否能正常傳送郵件，收件人地址需要填寫一個正確的 Email 地址，一般情況下是能夠傳送成功的。此外，還需要在 "評論設定" 選項中開啟 "評論回覆通知對方"，最後儲存設定。這樣，當博主回覆時，使用者的郵箱就可以收到博主回覆的內容了：

點贊

Halo 專案中，文章的點贊量是作為一個屬性封裝在 BasePost 實體中的，因此更新點贊量的時候需要更新 posts 資料表，這種處理方式在使用者量較少的個人部落格系統中是可行的，因為併發量一般不會超出資料庫的可承受範圍，而且由於普通使用者不需要登入，所以可以不用考慮使用者的取消點贊操作。但是需要注意的是，對於擁有大量使用者的部落格平臺或者社群論壇系統，此種方式就不再適用了，因為點贊操作是一個高頻呼叫的功能，頻繁運算元據庫可能會使伺服器崩潰。

下面我們分析一下點贊功能的實現過程，由於預設的主題 caicai_anatole 沒有提供點贊按鈕，所以我們將主題更換為 joe2.0（其它主題也可）。進入文章詳情頁，點選 "點贊" 按鈕後，觸發 /api/content/posts/1/likes 請求，該請求由 PostController 中的 like 方法處理：

@PostMapping("{postId:\\d+}/likes")
@ApiOperation("Likes a post")
@CacheLock(autoDelete = false, traceRequest = true)
public void like(@PathVariable("postId") @CacheParam Integer postId) {
    postService.increaseLike(postId);
}

like 方法呼叫 increaseLike 方法來增加點贊量，increaseLike 方法的處理邏輯也非常簡單，就是將 id 為 postId 的文章的點贊量加一 ρ（＾ o ＾）♪。

結語

本文以文章為例，介紹了評論和點贊功能的實現過程，由於對頁面的評論和點贊與之類似，因此便不再贅述了。