添加 utils.py 注释

djangoblog/src/DjangoBlog-master/DjangoBlog-master/comments/utils.py

@@ -1,17 +1,32 @@
+# gst: 导入日志模块，用于记录函数执行过程中的异常信息
 import logging
 
+# gst: 导入国际化翻译工具（别名_），支持邮件内容多语言显示
 from django.utils.translation import gettext_lazy as _
 
-from djangoblog.utils import get_current_site
-from djangoblog.utils import send_email
+# gst: 导入项目工具函数，用于获取当前站点信息和发送邮件
+from djangoblog.utils import get_current_site  # 获取当前站点域名
+from djangoblog.utils import send_email  # 邮件发送工具函数
 
+# gst: 初始化日志器，日志名称为当前模块名（便于定位日志来源）
 logger = logging.getLogger(__name__)
 
 
 def send_comment_email(comment):
+    """
+    gst: 评论邮件通知函数，发送两类邮件：
+    1. 给评论者的感谢邮件（确认评论提交成功）
+    2. 给父评论者的回复通知邮件（告知其评论收到回复）
+    :param comment: 评论对象（包含评论者、关联文章、父评论等信息）
+    """
+    # gst: 获取当前站点域名（用于拼接文章访问链接）
     site = get_current_site().domain
+    # gst: 邮件主题（支持国际化翻译）
     subject = _('Thanks for your comment')
+    # gst: 拼接文章的完整访问URL（HTTPS协议 + 站点域名 + 文章绝对路径）
     article_url = f"https://{site}{comment.article.get_absolute_url()}"
+
+    # gst: 构造给评论者的感谢邮件HTML内容
     html_content = _("""<p>Thank you very much for your comments on this site</p>
                     You can visit <a href="%(article_url)s" rel="bookmark">%(article_title)s</a>
                     to review your comments,
@@ -19,10 +34,16 @@ def send_comment_email(comment):
                     <br />
                     If the link above cannot be opened, please copy this link to your browser.
                     %(article_url)s""") % {'article_url': article_url, 'article_title': comment.article.title}
+
+    # gst: 获取评论者的邮箱地址（邮件接收人）
     tomail = comment.author.email
+    # gst: 发送感谢邮件（接收人列表、主题、HTML内容）
     send_email([tomail], subject, html_content)
+
     try:
+        # gst: 判断当前评论是否为回复（存在父评论）
         if comment.parent_comment:
+            # gst: 构造给父评论者的回复通知邮件HTML内容
             html_content = _("""Your comment on <a href="%(article_url)s" rel="bookmark">%(article_title)s</a><br/> has 
                    received a reply. <br/> %(comment_body)s
                     <br/>   
@@ -30,9 +51,15 @@ def send_comment_email(comment):
                      <br/>
                      If the link above cannot be opened, please copy this link to your browser.
                      %(article_url)s
-                    """) % {'article_url': article_url, 'article_title': comment.article.title,
-                            'comment_body': comment.parent_comment.body}
+                    """) % {
+                'article_url': article_url,  # 文章访问链接
+                'article_title': comment.article.title,  # 文章标题
+                'comment_body': comment.parent_comment.body  # 父评论的正文内容
+            }
+            # gst: 获取父评论者的邮箱地址（回复通知接收人）
             tomail = comment.parent_comment.author.email
+            # gst: 发送回复通知邮件
             send_email([tomail], subject, html_content)
     except Exception as e:
-        logger.error(e)
+        # gst: 捕获邮件发送过程中的异常，记录错误日志（不中断程序执行）
+        logger.error(e)