Перейти к содержанию

Spring Cloud Alibaba

Инструкция для микросервисов на Spring Cloud Alibaba и Spring Boot 3.5.x (Java, JVM). Mailexam® подключается через spring-boot-starter-mail и JavaMailSender — тот же SMTP-стек, что в Spring Boot, внутри сервиса Spring Cloud Alibaba.

Что понадобится

  • Аккаунт Mailexam® и проект с SMTP-учётными данными.
  • JDK 17+ и проект Spring Cloud Alibaba (Gradle или Maven).

Скопируйте из приветственного письма (или кабинета) для вашего проекта:

  • ВАШ_ЛОГИН — SMTP-логин (например, xxxxx);
  • ВАШ_ПАРОЛЬ — SMTP-пароль (уникальная пара к логину);
  • хост — ВАШ_ЛОГИН.mailexam.ru (совпадает с логином).

1. Зависимости

Добавьте BOM Spring Cloud и Spring Cloud Alibaba, затем mail и (опционально) Nacos discovery.

Gradle (build.gradle):

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.5.0'
    id 'io.spring.dependency-management' version '1.1.7'
}

ext {
    set('springCloudVersion', '2025.0.0')
    set('springCloudAlibabaVersion', '2025.0.0.0')
}

dependencyManagement {
    imports {
        mavenBom "org.springframework.cloud:spring-cloud-dependencies:${springCloudVersion}"
        mavenBom "com.alibaba.cloud:spring-cloud-alibaba-dependencies:${springCloudAlibabaVersion}"
    }
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-mail'
    implementation 'com.alibaba.cloud:spring-cloud-starter-alibaba-nacos-discovery'
}

Для Maven — импортируйте те же BOM и добавьте три starter'а.

Nacos необязателен для проверки SMTP

Nacos discovery включён для типичной структуры Spring Cloud Alibaba, но локально его можно отключить (см. раздел 3) и тестировать почту без сервера Nacos.

2. Переменные окружения

Файл .env для локальной разработки (не коммитьте пароли) или переменные в Run Configuration / CI:

MAILEXAM_LOGIN=ВАШ_ЛОГИН
MAILEXAM_PASSWORD=ВАШ_ПАРОЛЬ
MAILEXAM_PORT=587
MAIL_FROM=noreply@example.test
NACOS_DISCOVERY_ENABLED=false
NACOS_SERVER_ADDR=127.0.0.1:8848

SMTP-хост в конфигурации: ${MAILEXAM_LOGIN}.mailexam.ru.

Адрес отправителя

MAIL_FROM может быть любым тестовым адресом — письмо попадёт в Mailexam®, а не реальному получателю.

Альтернативные порты

MAILEXAM_PORT=587

spring.mail.properties.mail.smtp.starttls.enable=true

MAILEXAM_PORT=2525

STARTTLS, как для 587.

MAILEXAM_PORT=25

spring.mail.properties.mail.smtp.starttls.enable=false

3. Конфигурация приложения

Включите discovery на главном классе:

@SpringBootApplication
@EnableDiscoveryClient
public class MailServiceApplication {
    public static void main(String[] args) {
        SpringApplication.run(MailServiceApplication.class, args);
    }
}

src/main/resources/application.yml:

spring:
  application:
    name: mail-service
  cloud:
    nacos:
      discovery:
        enabled: ${NACOS_DISCOVERY_ENABLED:false}
        server-addr: ${NACOS_SERVER_ADDR:127.0.0.1:8848}
  mail:
    host: ${MAILEXAM_LOGIN}.mailexam.ru
    port: ${MAILEXAM_PORT:587}
    username: ${MAILEXAM_LOGIN}
    password: ${MAILEXAM_PASSWORD}
    properties:
      mail.smtp.auth: true
      mail.smtp.starttls.enable: true

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

Для порта 25 задайте mail.smtp.starttls.enable=false (см. таблицу выше).

4. Сервис отправки

package com.example.demo.mail;

import jakarta.mail.MessagingException;
import jakarta.mail.internet.MimeMessage;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.mail.javamail.JavaMailSender;
import org.springframework.mail.javamail.MimeMessageHelper;
import org.springframework.stereotype.Service;

@Service
public class MailService {

    private final JavaMailSender mailSender;
    private final String from;

    public MailService(JavaMailSender mailSender, @Value("${mail.from}") String from) {
        this.mailSender = mailSender;
        this.from = from;
    }

    public void sendTest(String to, String subject, String body) throws MessagingException {
        MimeMessage message = mailSender.createMimeMessage();
        MimeMessageHelper helper = new MimeMessageHelper(message, "UTF-8");
        helper.setFrom(from);
        helper.setTo(to);
        helper.setSubject(subject);
        helper.setText(body, false);
        mailSender.send(message);
    }
}

5. REST-эндпоинт

package com.example.demo.web;

import com.example.demo.mail.MailService;
import jakarta.mail.MessagingException;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

import java.util.Map;

@RestController
public class MailController {

    private final MailService mailService;

    public MailController(MailService mailService) {
        this.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 = "Spring Cloud Alibaba + Mailexam";
            }
            if (body == null || body.isBlank()) {
                body = "Тест Mailexam из Spring Cloud Alibaba";
            }
        }
    }

    @PostMapping("/mail/test")
    public Map<String, String> sendTest(@RequestBody SendRequest request) throws MessagingException {
        mailService.sendTest(request.to(), request.subject(), request.body());
        return Map.of("status", "ok");
    }
}

Запуск и проверка:

./gradlew bootRun

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® → ваш проект → входящие.

6. Локальная разработка и CI

Среда Рекомендация
local переменные в IDE или .env; без Nacos держите NACOS_DISCOVERY_ENABLED=false
CI секреты MAILEXAM_LOGIN, MAILEXAM_PASSWORD в переменных pipeline

Пример для GitLab CI:

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

После интеграционного теста проверьте доставку через API Mailexam®.

7. Типичные проблемы

Ошибка TLS или подключения

  • spring.mail.host должен быть {логин}.mailexam.ru, username — тот же логин из письма.
  • Логин и пароль — пара из письма одного проекта.

Ошибки подключения к Nacos при старте

  • Для локальной проверки SMTP задайте NACOS_DISCOVERY_ENABLED=false.
  • При включённом discovery убедитесь, что Nacos доступен по NACOS_SERVER_ADDR.

Переменные не подставляются

  • Запускайте приложение с заданными MAILEXAM_LOGIN и MAILEXAM_PASSWORD; в IDE проверьте Environment в конфигурации Run.

Письмо не в кабинете

  • Смотрите входящие того же проекта Mailexam®.
  • Включите логирование: logging.level.org.springframework.mail=DEBUG.

См. также