配置

Spring Boot 邮件属性

使用 Spring Boot 邮件属性 设置基本的电子邮件发送参数,例如,协议、主机、端口等。

示例:

spring.mail.host=smtp.company.com
spring.mail.port=587
spring.mail.protocol=smtp
spring.mail.username=username
spring.mail.password=password

另外,可以用 spring.mail.properties.* 格式指定 JavaMail 属性。例如,mail.smtp.auth 属性可以这样设置:

spring.mail.properties.mail.smtp.auth=true

Jmix 邮件属性

Jmix 邮件属性支持对 电子邮件 API 部分的功能进行配置。

jmix.email.from-address

设置默认的发件人地址。如果 EmailInfo.from 未定义,则使用该值。

默认值:DoNotReply@localhost

jmix.email.scheduled-sending-delay-call-count

属性用于异步发送电子邮件,在服务器启动后跳过前几次调用 Emailer.processQueuedEmails(),以减少应用程序初始化期间的负载。邮件发送将从下一个调用开始。

默认值:2

jmix.email.message-queue-capacity

属性用于异步发送,设置一次调用 Emailer.processQueuedEmails() 时,从队列中读取并发送的最大邮件数量。

默认值:100

jmix.email.default-sending-attempts-limit

属性用于异步发送,设置默认尝试发送邮件的次数。如果调用 Emailer.sendEmailAsync() 时未指定 attemptsCount 参数,则使用该参数。

默认值:10

jmix.email.sending-timeout-sec

设置将电子邮件发送到 SMTP 服务器所需的最大期望时间(以秒为单位)。用于异步发送,用于优化从 DB 队列中选择 SendingMessage 对象的速度。

默认值:240

jmix.email.admin-addresss

设置一个收件人地址,如果启用 jmix.email.send-all-to-admin 属性,所有邮件都将发送到该地址。

默认值:admin@localhost

jmix.email.send-all-to-admin

设置将所有邮件都发送到 jmix.email.admin-address 地址,无论收件人地址是什么。建议在系统开发和调试时使用该参数。

默认值:false

jmix.email.use-file-storage

启用后,电子邮件正文和附件将保存在文件存储中,而不是数据库的 BLOB 列中。如果应用程序需要存储大量邮件或邮件附件,则应该使用文件存储。

默认值:false

jmix.email.async-sending-username

设置系统用户的登录名,异步邮件发送的代码使用该用户名将信息持久化保存到数据库中。建议创建一个没有密码的单独用户(例如,emailer),无法通过用户界面使用此用户名登录。另外,也方便在服务器日志中搜索与邮件发送相关的消息。

默认值:admin

jmix.email.use-default-quartz-configuration

设置是否使用 默认 Quartz 配置 发送邮件。

默认值:true

jmix.email.email-sending-cron

设置发送邮件 Quartz 调度使用的默认 cron 表达式。

默认值:0 * * * * ?(每分钟)

jmix.email.use-default-email-cleaning-quartz-configuration

设置是否使用 默认 Quartz 配置 清理邮件。

默认值:false

jmix.email.email-cleaning-cron

设置清理邮件 Quartz 调度使用的默认 cron 表达式。

默认值:0 0 0 * * ?(每天 0 点)

jmix.email.max-age-of-important-messages

设置重要邮件保留的最长时间(以天为单位),超时后,邮件将被删除。零值(0)表示不删除。

默认值:0

jmix.email.max-age-of-non-important-messages

设置普通邮件保留的最长时间(以天为单位),超时后,邮件将被删除。零值(0)表示不删除。

默认值:0

jmix.email.clean-file-storage

设置是否在清理邮件调度器工作时也同时清理文件存储。

默认值:false

邮件发送调度器

当调用 Emailer.sendEmailAsync() 方法时,邮件并未发送,而是进入数据库排队。如需发送队列中的邮件,需要调用 Emailer.processQueuedEmails() 方法。

你可以使用 Quartz Job Scheduler 周期性地处理邮件队列。

默认 Quartz 配置

电子邮件扩展组件提供 Quartz 任务的默认配置,用于处理邮件发送队列。按照下列步骤使用:

  1. 为项目添加 Quartz 扩展组件,按照 Quartz 安装 章节的说明进行添加。

  2. 如果需要的话,用 jmix.email.email-sending-cron 应用程序属性修改 cron 表达式:

    jmix.email.email-sending-cron=* 0/2 * * * ?

自定义 Quartz 配置

如需使用自定义的 Quartz 任务配置,按照下列步骤:

  1. 为项目添加 Quartz 扩展组件,按照 Quartz 安装 章节的说明进行添加。

  2. 设置 jmix.email.use-default-quartz-configuration 应用程序属性为 false

    jmix.email.use-default-quartz-configuration = false
  3. 创建一个任务类:

    public class MyCustomEmailSendingJob implements Job {
    
        @Autowired
        private Emailer emailer;
    
        @Override
        public void execute(JobExecutionContext context) throws JobExecutionException {
            emailer.processQueuedEmails();
        }
    }
  4. 在运行的应用程序中,打开 Administration(管理) → Quartz jobs(Quartz 任务) 界面,并为 MyCustomEmailSendingJob 类配置一个任务。

  5. 或者,如果需要在开发阶段配置邮件发送的任务,将下面的 bean 添加至主应用程序类:

    @Bean
    JobDetail myCustomEmailSendingJob() {
        return JobBuilder.newJob()
                .ofType(MyCustomEmailSendingJob.class)
                .storeDurably()
                .withIdentity("emailSending")
                .build();
    }
    
    @Bean
    Trigger myCustomEmailSendingTrigger() {
        return TriggerBuilder.newTrigger()
                .forJob(myCustomEmailSendingJob())
                .startNow()
                .withSchedule(CronScheduleBuilder.cronSchedule("* 0/2 * * * ?"))
                .build();
    }

邮件清理调度器

该扩展组件带有一个内置的邮件清理 Quartz 任务,默认是关闭的。可以按照下列步骤使用这个任务周期性地清理邮件。

如需将某些邮件保存长一些,可以使用 important(重要) 标签进行标记,并设置重要和普通邮件的最长保存时间。可以通过 EmailInfoBuildersetImportant() 方法设置该标记。

默认 Quartz 配置

如需使用清理邮件的默认 Quartz job 配置,按照下列步骤:

  1. 为项目添加 Quartz 扩展组件,按照 Quartz 安装 章节的说明进行添加。

  2. 设置 jmix.email.use-default-email-cleaning-quartz-configuration 属性为 true

    jmix.email.use-default-email-cleaning-quartz-configuration=true
  3. 如果需要的话,用 jmix.email.email-cleaning-cron 应用程序属性修改 cron 表达式:

    jmix.email.email-cleaning-cron=0 0 0 1/2 * ?
  4. 设置重要和普通邮件的保存时长,使用 jmix.email.max-age-of-important-messagesjmix.email.max-age-of-non-important-messages 属性,示例:

    jmix.email.max-age-of-non-important-messages=5
    jmix.email.max-age-of-important-messages=30
  5. 如需删除附件,设置 jmix.email.clean-file-storage 属性为 true

自定义 Quartz 配置

如需使用自定义的 Quartz 任务配置,按照下列步骤:

  1. 为项目添加 Quartz 扩展组件,按照 Quartz 安装 章节的说明进行添加。

  2. 创建一个任务类:

    public class MyCustomEmailCleaningJob implements Job {
    
        @Autowired
        private EmailCleaner emailCleaner;
    
        @Override
        public void execute(JobExecutionContext context) throws JobExecutionException {
            emailCleaner.deleteOldEmails();
        }
    }
  3. 在运行的应用程序中,打开 Administration(管理) → Quartz jobs(Quartz 任务) 界面,然后为 MyCustomEmailCleaningJob 类配置一个任务。

  4. 或者,如果需要在开发阶段配置邮件清理的任务,将下面的 bean 添加至主应用程序类:

    @Bean
    JobDetail myCustomEmailCleaningJob() {
        return JobBuilder.newJob()
                .ofType(MyCustomEmailCleaningJob.class)
                .storeDurably()
                .withIdentity("emailCleaning")
                .build();
    }
    
    @Bean
    Trigger MyCustomEmailCleaningTrigger() {
        return TriggerBuilder.newTrigger()
                .forJob(myCustomEmailCleaningJob())
                .startNow()
                .withSchedule(CronScheduleBuilder.cronSchedule("0 0 0 1/2 * ? "))
                .build();
    }
  5. 设置重要和普通邮件的保存时长,使用 jmix.email.max-age-of-important-messagesjmix.email.max-age-of-non-important-messages 属性,示例:

    jmix.email.max-age-of-non-important-messages=5
    jmix.email.max-age-of-important-messages=30
  6. 如需删除附件,设置 jmix.email.clean-file-storage 属性为 true

使用文件存储

电子邮件正文和附件可以保存在文件存储中,而不是数据库的 BLOB 列中。

使用文件存储:

  1. build.gradle 文件的 dependencies 部分添加如下内容:

    implementation 'io.jmix.localfs:jmix-localfs-starter'
  2. application.properties 文件中设置启用文件存储:

    jmix.email.use-file-storage=true

默认情况下,本地文件存储位于应用程序的工作目录:${user.dir}/.jmix/work/filestorage