跳转至

Quarkus

适用于 Quarkus 3.x（Java，JVM）应用的集成指南。Mailexam 通过 quarkus-mailer 扩展及 Mailer API 接入。

前置条件

  • Mailexam 账户，以及已创建并具备 SMTP 凭据的项目。
  • JDK 17+ 及 Quarkus 项目（通过 code.quarkus.io 或手动创建）。

从项目的欢迎邮件（或控制台）中复制：

  • YOUR_LOGIN — SMTP 登录名（例如 xxxxx）；
  • YOUR_PASSWORD — SMTP 密码（与登录名成对的唯一凭据）；
  • 主机 — YOUR_LOGIN.mailexam.cn（与登录名一致）。

1. 依赖

在 code.quarkus.io 选择 REST 和 Mailer，或在 build.gradle 中添加：

plugins {
    id 'java'
    id 'io.quarkus' version '3.20.1'
}

repositories {
    mavenCentral()
}

dependencies {
    implementation enforcedPlatform("${quarkusPlatformGroupId}:${quarkusPlatformArtifactId}:${quarkusPlatformVersion}")
    implementation 'io.quarkus:quarkus-rest'
    implementation 'io.quarkus:quarkus-mailer'
    implementation 'io.quarkus:quarkus-arc'
}

在 gradle.properties 中添加：

quarkusPlatformGroupId=io.quarkus.platform
quarkusPlatformArtifactId=quarkus-bom
quarkusPlatformVersion=3.20.1

Maven 使用相同扩展 quarkus-rest 和 quarkus-mailer。

2. 环境变量

本地开发的 .env 文件（勿将密码提交到 git），或在 Run Configuration / CI 中设置变量：

MAILEXAM_LOGIN=YOUR_LOGIN
MAILEXAM_PASSWORD=YOUR_PASSWORD
MAILEXAM_PORT=587
MAIL_FROM=noreply@example.test

配置中的 SMTP 主机：${MAILEXAM_LOGIN}.mailexam.cn（GitHub 参考实现 中域名为 mailexam.io，请按欢迎邮件中的主机填写）。

发件人地址

MAIL_FROM 可以是任意测试地址——邮件仍会进入 Mailexam，而非真实收件人。

备选端口

MAILEXAM_PORT=587

quarkus.mailer.start-tls=REQUIRED

MAILEXAM_PORT=2525

与 587 相同，需要 STARTTLS。

MAILEXAM_PORT=25

quarkus.mailer.start-tls=DISABLED

3. 邮件配置

src/main/resources/application.properties：

quarkus.http.host=${HTTP_HOST:127.0.0.1}
quarkus.http.port=${HTTP_PORT:8080}

mail.from=${MAIL_FROM:noreply@example.test}

quarkus.mailer.from=${mail.from}
quarkus.mailer.host=${MAILEXAM_LOGIN}.mailexam.cn
quarkus.mailer.port=${MAILEXAM_PORT:587}
quarkus.mailer.username=${MAILEXAM_LOGIN}
quarkus.mailer.password=${MAILEXAM_PASSWORD}
quarkus.mailer.start-tls=REQUIRED
quarkus.mailer.auth-methods=PLAIN

端口 25 时请将 quarkus.mailer.start-tls=DISABLED（见上表）。

4. 发送服务

package com.example.demo.mail;

import io.quarkus.mailer.Mail;
import io.quarkus.mailer.Mailer;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;
import org.eclipse.microprofile.config.inject.ConfigProperty;

@ApplicationScoped
public class MailService {

    private final Mailer mailer;
    private final String from;

    @Inject
    public MailService(Mailer mailer, @ConfigProperty(name = "mail.from") String from) {
        this.mailer = mailer;
        this.from = from;
    }

    public void sendTest(String to, String subject, String body) {
        mailer.send(Mail.withText(to, subject, body).setFrom(from));
    }
}

5. REST 端点

package com.example.demo.web;

import com.example.demo.mail.MailService;
import jakarta.inject.Inject;
import jakarta.ws.rs.Consumes;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;
import java.util.Map;

@Path("/mail")
public class MailController {

    @Inject
    MailService mailService;

    public record SendRequest(String to, String subject, String body) {
        public SendRequest {
            if (to == null || to.isBlank()) {
                to = "user@example.test";
            }
            if (subject == null || subject.isBlank()) {
                subject = "Quarkus + Mailexam";
            }
            if (body == null || body.isBlank()) {
                body = "Mailexam test from Quarkus";
            }
        }
    }

    @POST
    @Path("/test")
    @Consumes(MediaType.APPLICATION_JSON)
    @Produces(MediaType.APPLICATION_JSON)
    public Map<String, String> sendTest(SendRequest request) {
        mailService.sendTest(request.to(), request.subject(), request.body());
        return Map.of("status", "ok");
    }
}

启动并验证：

./gradlew quarkusDev

curl -X POST http://127.0.0.1:8080/mail/test \
  -H 'Content-Type: application/json' \
  -d '{"to":"user@example.test","subject":"Test","body":"Hello"}'

邮件将出现在 Mailexam 控制台 → 您的项目 → 收件箱。

完整示例见 Quarkus 实现示例（GitHub）。

6. 本地开发与 CI

环境 建议
local IDE 环境变量，或 .env + Gradle envfile 插件
CI 在 GitLab CI/CD Variables 中设置 MAILEXAM_LOGIN、MAILEXAM_PASSWORD

.gitlab-ci.yml 示例：

variables:
  MAILEXAM_LOGIN: $MAILEXAM_LOGIN
  MAILEXAM_PASSWORD: $MAILEXAM_PASSWORD
  MAILEXAM_PORT: "587"
  MAIL_FROM: "noreply@example.test"

集成测试后，通过 Mailexam API 验证投递。

7. 常见问题

TLS 或连接错误

  • quarkus.mailer.host 应为 {login}.mailexam.cn，username 为邮件中的同一登录名。
  • 登录名与密码须为同一项目欢迎邮件中的成对凭据。

变量未替换

  • 运行应用前设置 MAILEXAM_LOGIN 和 MAILEXAM_PASSWORD；在 IDE 中检查 Run 配置里的 Environment。

控制台中看不到邮件

  • 查看同一 Mailexam 项目的收件箱。
  • 启用日志：quarkus.log.category."io.quarkus.mailer".level=DEBUG。

参见