espeak-ng

How To Install espeak-ng on CentOS 8 | Installati.one

How to install eSpeak on CentOS 8 / Ubuntu 20.04 / 18.04? - Linux Windows and android Tutorials

eSpeak NG 安装和配置指南-CSDN博客

eSpeak NG，適用於 Linux 的文本到語音合成器

eSpeak NG (Next Generation) Text-to-Speech 是 open source speech synthesizer。使用了共振峰合成方法，用比較小的程式提供多種語言的合成方法。

1995年 Jonathan Duddington 提出在 RISC OS 運作，支援 British English 的語音合成器，後來在 2006/2/17，speak 1.05 以 GPLv2 released。目前已重新命名為 eSpeak

2010/6/25 Reece Dunn 在 github 以 1.43.46 版發起 eSpeak 的 fork，致力於讓 eSpeak 運作在其他 POSIX plarforms。到了 2015/12/11 epeak-ng 啟動，支援更多語言，且做了更多 bug fix。

CLI

# espeak-ng --help
eSpeak NG text-to-speech: 1.49.2  Data at: /usr/share/espeak-ng-data

espeak-ng [options] ["<words>"]

-f <text file>   Text file to speak
--stdin    Read text input from stdin instead of a file

If neither -f nor --stdin, then <words> are spoken, or if none then text
is spoken from stdin, each line separately.

-a <integer>
       Amplitude, 0 to 200, default is 100
-d <device>
       Use the specified device to speak the audio on. If not specified, the
       default audio device is used.
-g <integer>
       Word gap. Pause between words, units of 10mS at the default speed
-k <integer>
       Indicate capital letters with: 1=sound, 2=the word "capitals",
       higher values indicate a pitch increase (try -k20).
-l <integer>
       Line length. If not zero (which is the default), consider
       lines less than this length as end-of-clause
-p <integer>
       Pitch adjustment, 0 to 99, default is 50
-s <integer>
       Speed in approximate words per minute. The default is 175
-v <voice name>
       Use voice file of this name from espeak-ng-data/voices
-w <wave file name>
       Write speech to this WAV file, rather than speaking it directly
-b       Input text encoding, 1=UTF8, 2=8 bit, 4=16 bit
-m       Interpret SSML markup, and ignore other < > tags
-q       Quiet, don't produce any speech (may be useful with -x)
-x       Write phoneme mnemonics to stdout
-X       Write phonemes mnemonics and translation trace to stdout
-z       No final sentence pause at the end of the text
--compile=<voice name>
       Compile pronunciation rules and dictionary from the current
       directory. <voice name> specifies the language
--compile-debug=<voice name>
       Compile pronunciation rules and dictionary from the current
       directory, including line numbers for use with -X.
       <voice name> specifies the language
--compile-mbrola=<voice name>
       Compile an MBROLA voice
--compile-intonations
       Compile the intonation data
--compile-phonemes=<phsource-dir>
       Compile the phoneme data using <phsource-dir> or the default phsource directory
--ipa      Write phonemes to stdout using International Phonetic Alphabet
--path="<path>"
       Specifies the directory containing the espeak-ng-data directory
--pho      Write mbrola phoneme data (.pho) to stdout or to the file in --phonout
--phonout="<filename>"
       Write phoneme output from -x -X --ipa and --pho to this file
--punct="<characters>"
       Speak the names of punctuation characters during speaking.  If
       =<characters> is omitted, all punctuation is spoken.
--sep=<character>
       Separate phonemes (from -x --ipa) with <character>.
       Default is space, z means ZWJN character.
--split=<minutes>
       Starts a new WAV file every <minutes>.  Used with -w
--stdout   Write speech output to stdout
--tie=<character>
       Use a tie character within multi-letter phoneme names.
       Default is U+361, z means ZWJ character.
--version  Shows version number and date, and location of espeak-ng-data
--voices=<language>
       List the available voices for the specified language.
       If <language> is omitted, then list all voices.
-h, --help Show this help.

# espeak-ng --voices
Pty Language       Age/Gender VoiceName          File                 Other Languages
 5  af              --/M      Afrikaans          gmw/af
 5  am              --/M      Amharic            sem/am
 5  an              --/M      Aragonese          roa/an
 5  ar              --/M      Arabic             sem/ar
 5  as              --/M      Assamese           inc/as
 5  az              --/M      Azerbaijani        trk/az
 5  bg              --/M      Bulgarian          zls/bg
 5  bn              --/M      Bengali            inc/bn
 5  bpy             --/M      Bishnupriya_Manipuri inc/bpy
 5  bs              --/M      Bosnian            zls/bs
 5  ca              --/M      Catalan            roa/ca
 5  cmn             --/M      Chinese_(Mandarin) sit/cmn              (zh-cmn 5)(zh 5)
 5  cs              --/M      Czech              zlw/cs
 5  cy              --/M      Welsh              cel/cy
 5  da              --/M      Danish             gmq/da
 5  de              --/M      German             gmw/de
 5  el              --/M      Greek              grk/el
 5  en-029          --/M      English_(Caribbean) gmw/en-029           (en 10)
 2  en-gb           --/M      English_(Great_Britain) gmw/en               (en 2)
 5  en-gb-scotland  --/M      English_(Scotland) gmw/en-GB-scotland   (en 4)
 5  en-gb-x-gbclan  --/M      English_(Lancaster) gmw/en-GB-x-gbclan   (en-gb 3)(en 5)
 5  en-gb-x-gbcwmd  --/M      English_(West_Midlands) gmw/en-GB-x-gbcwmd   (en-gb 9)(en 9)
 5  en-gb-x-rp      --/M      English_(Received_Pronunciation) gmw/en-GB-x-rp       (en-gb 4)(en 5)
 2  en-us           --/M      English_(America)  gmw/en-US            (en 3)
 5  eo              --/M      Esperanto          art/eo
 5  es              --/M      Spanish_(Spain)    roa/es
 5  es-419          --/M      Spanish_(Latin_America) roa/es-419           (es-mx 6)(es 6)
 5  et              --/M      Estonian           urj/et
 5  eu              --/M      Basque             eu
 5  fa              --/M      Persian            ira/fa
 5  fa-Latn         --/M      Persian_(Pinglish) ira/fa-Latn
 5  fi              --/M      Finnish            urj/fi
 5  fr-be           --/M      French_(Belgium)   roa/fr-BE            (fr 8)
 5  fr-ch           --/M      French_(Switzerland) roa/fr-CH            (fr 8)
 5  fr-fr           --/M      French_(France)    roa/fr               (fr 5)
 5  ga              --/M      Gaelic_(Irish)     cel/ga
 5  gd              --/M      Gaelic_(Scottish)  cel/gd
 5  gn              --/M      Guarani            sai/gn
 5  grc             --/M      Greek_(Ancient)    grk/grc
 5  gu              --/M      Gujarati           inc/gu
 5  hi              --/M      Hindi              inc/hi
 5  hr              --/M      Croatian           zls/hr               (hbs 5)
 5  hu              --/M      Hungarian          urj/hu
 5  hy              --/M      Armenian_(East_Armenia) ine/hy               (hy-arevela 5)
 5  hy-arevmda      --/M      Armenian_(West_Armenia) ine/hy-arevmda       (hy 8)
 5  ia              --/M      Interlingua        art/ia
 5  id              --/M      Indonesian         poz/id
 5  is              --/M      Icelandic          gmq/is
 5  it              --/M      Italian            roa/it
 5  ja              --/M      Japanese           jpx/ja
 5  jbo             --/M      Lojban             art/jbo
 5  ka              --/M      Georgian           ccs/ka
 5  kl              --/M      Greenlandic        esx/kl
 5  kn              --/M      Kannada            dra/kn
 5  ko              --/M      Korean             ko
 5  kok             --/M      Konkani            inc/kok
 5  ku              --/M      Kurdish            ira/ku
 5  ky              --/M      Kyrgyz             trk/ky
 5  la              --/M      Latin              itc/la
 5  lfn             --/M      Lingua_Franca_Nova art/lfn
 5  lt              --/M      Lithuanian         bat/lt
 5  lv              --/M      Latvian            bat/lv
 5  mi              --/M      poz/mi             poz/mi
 5  mk              --/M      Macedonian         zls/mk
 5  ml              --/M      Malayalam          dra/ml
 5  mr              --/M      Marathi            inc/mr
 5  ms              --/M      Malay              poz/ms
 5  mt              --/M      Maltese            sem/mt
 5  my              --/M      Burmese            sit/my
 5  nb              --/M      Norwegian_Bokmål  gmq/nb               (no 5)
 5  nci             --/M      Nahuatl_(Classical) azc/nci
 5  ne              --/M      Nepali             inc/ne
 5  nl              --/M      Dutch              gmw/nl
 5  om              --/M      Oromo              cus/om
 5  or              --/M      Oriya              inc/or
 5  pa              --/M      Punjabi            inc/pa
 5  pap             --/M      Papiamento         roa/pap
 5  pl              --/M      Polish             zlw/pl
 5  pt              --/M      Portuguese_(Portugal) roa/pt               (pt-pt 5)
 5  pt-br           --/M      Portuguese_(Brazil) roa/pt-BR            (pt 6)
 5  ro              --/M      Romanian           roa/ro
 5  ru              --/M      Russian            zle/ru
 5  sd              --/M      Sindhi             inc/sd
 5  si              --/M      Sinhala            inc/si
 5  sk              --/M      Slovak             zlw/sk
 5  sl              --/M      Slovenian          zls/sl
 5  sq              --/M      Albanian           ine/sq
 5  sr              --/M      Serbian            zls/sr
 5  sv              --/M      Swedish            gmq/sv
 5  sw              --/M      Swahili            bnt/sw
 5  ta              --/M      Tamil              dra/ta
 5  te              --/M      Telugu             dra/te
 5  tn              --/M      Setswana           bnt/tn
 5  tr              --/M      Turkish            trk/tr
 5  tt              --/M      Tatar              trk/tt
 5  ur              --/M      Urdu               inc/ur
 5  vi              --/M      Vietnamese_(Northern) aav/vi
 5  vi-vn-x-central --/M      Vietnamese_(Central) aav/vi-VN-x-central
 5  vi-vn-x-south   --/M      Vietnamese_(Southern) aav/vi-VN-x-south
 5  yue             --/M      Chinese_(Cantonese) sit/yue              (zh-yue 5)(zh 8)

espeak-ng-data 的路徑

ls /usr/share/espeak-ng-data
af_dict   ca_dict  eu_dict   hu_dict      kl_dict   lv_dict    ne_dict            phontab  sr_dict  voices
am_dict   cs_dict  fa_dict   hy_dict      kn_dict   mbrola_ph  nl_dict            pl_dict  sv_dict  zh_dict
an_dict   cy_dict  fi_dict   ia_dict      ko_dict   mi_dict    no_dict            pt_dict  sw_dict  zhy_dict
ar_dict   da_dict  fr_dict   id_dict      kok_dict  mk_dict    om_dict            ro_dict  ta_dict
as_dict   de_dict  ga_dict   intonations  ku_dict   ml_dict    or_dict            ru_dict  te_dict
az_dict   el_dict  gd_dict   is_dict      ky_dict   mr_dict    pa_dict            sd_dict  tn_dict
bg_dict   en_dict  grc_dict  it_dict      la_dict   ms_dict    pap_dict           si_dict  tr_dict
bn_dict   eo_dict  gu_dict   ja_dict      lang      mt_dict    phondata           sk_dict  tt_dict
bpy_dict  es_dict  hi_dict   jbo_dict     lfn_dict  my_dict    phondata-manifest  sl_dict  ur_dict
bs_dict   et_dict  hr_dict   ka_dict      lt_dict   nci_dict   phonindex          sq_dict  vi_dict

從已編譯的 espeak-ng 版本是 1.49.2 版，但安裝後發現該版本不支援中文

# rpm -qa|grep espeak
espeak-ng-1.49.2-4.el8.x86_64

到 github 下載 1.52 版

wget https://github.com/espeak-ng/espeak-ng/archive/refs/tags/1.52.0.tar.gz

直接編譯

ref: questions about mandarin data packet · Issue #1044 · espeak-ng/espeak-ng · GitHub

./autogen.sh
./configure --with-extdict-cmn

這邊最後要看到

        Extended Dictionaries:
            Russian:                   yes
            Chinese (Mandarin):        yes
            Chinese (Cantonese):       yes

編譯

make
make install

測試

espeak-ng -v cmn "english text 你好 more english text" -w test1.wav

Spring Boot 3 Actuator

Actuator 一般用在 production 環境，使用 http endpoint 或 JMX 方式監控 app，然後抓取指標數值給資料監控平台。

以此順序介紹 Actuator -> Endpoints -> Metrics -> Grafana

---

要啟用 actuator，只需要加上 library

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-actuator</artifactId>
        </dependency>

---

Endpoint

ref: Endpoints :: Spring Boot

endpoint 是用來監控 spring boot app，spring boot 內建很多endpoints，每個 endpoint 都可透過 http/JMX 方式暴露出去，大部分都是用 http。endpoint 會映射為 /actuator/${ID} ID 就是 endpoint 的 ID，ex: /actuator/health

啟動 app 後，瀏覽網址 http://localhost:8080/actuator/health

結果 UP 代表健康運作中

{
    "status": "UP"
}

spring boot 內建的 endpoints

name	desc
auditevents	當前 app 的 audit event
beans	所有 spring beans
caches	可使用的 cache
conditions	設定類別上評估條件及匹配成功與否的原因
configprops	所有 @ConfigurationProperties list
env	spring 環境中暴露的所有 properties
flyway	所有 flyway 遷移記錄
health	健康資訊
httpexchanges	http exchange message(預設顯示最新的 100個)
info	app basic info
integrationgraph	spring integration graph
loggers	顯示/修改 logger 設定
liquibase	顯示 liquibase db migration
metrics	metric infos
mappings	顯示所有 @RequestMapping
quartz	顯示 quartz jobs
scheduledtasks	顯示 scheduled tasks
sessions	當有 servlet-based web app 使用 Spring Session 時，查詢/刪除 user sessions
shutdown	關閉 app
startup	顯示啟動的資料
threaddump	thread dump

使用 web app 時，還有以下這些

name	desc
heapdump	回傳 heap dump。HotSpot VM 是回傳 HPROF-format file。OpenJ9 JVM 是回傳 PHD-format file
logfile	log file content (需要設定 logging.file.name/logging.file.path)
prometheus	可被 prometheus server 提取的 metric

除了 shotdown 其他所有 endpoint 預設都是開啟的。可透過 management.endpoint.<id>.enabled 啟用/禁用 endpoint。

ex:

management:
  endpoint:
    shutdown:
      enabled: true

禁用所有 endpoint, 只啟用某一個 endpoint

management:
  endpoints:
    enable-by-default: false
  endpoint:
    shutdown:
      enabled: true

---

expose endpoint

啟用後，不一定能被存取。spring boot 3 預設只以 JMX, Web 方式暴露了 health

Property	Default
management.endpoints.jmx.exposure.exclude
management.endpoints.jmx.exposure.include	health
management.endpoints.web.exposure.exclude
management.endpoints.web.exposure.include	health

management:
  endpoints:
    jmx:
      exposure:
        include: "health,info"
    web:
      exposure:
        include: "*"
        exclude: "env,beans"

security

endpoint 提供的資訊需要安全保護

只要有 Spring Security library，就會自動保護所有 endpoints

實作 actuator 的 ManagementWebSecurityAutoConfiguration

註冊在 spring-boot-actuator-autoconfigure

修改 pom.xml 後

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-security</artifactId>
        </dependency>

存取 http://localhost:8080/actuator/info 會自動轉到 Please sign in

---

如果不想使用 spring boot 預設機制，可改用 SecurityFilterChain

package com.test.actuator;

import org.springframework.boot.actuate.autoconfigure.security.servlet.EndpointRequest;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.core.userdetails.User;
import org.springframework.security.core.userdetails.UserDetailsService;
import org.springframework.security.provisioning.InMemoryUserDetailsManager;
import org.springframework.security.web.SecurityFilterChain;

import static org.springframework.security.config.Customizer.withDefaults;

@Configuration
public class SecurityConfig {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        return http.authorizeHttpRequests((authorize) -> {
                    authorize.requestMatchers("/").permitAll()
                            .requestMatchers(EndpointRequest.to("health")).hasRole("ENDPOINT_ADMIN")
                            .requestMatchers(EndpointRequest.toAnyEndpoint()).permitAll();
                })
                //                .csrf(csrf -> csrf.disable())
                .csrf(csrf -> csrf.ignoringRequestMatchers(EndpointRequest.toAnyEndpoint()))
                .formLogin(withDefaults())
                .logout(logout -> logout.logoutUrl("/"))
                .build();
    }

    @Bean
    protected UserDetailsService userDetailsService() {
        InMemoryUserDetailsManager manager = new InMemoryUserDetailsManager();
        manager.createUser(User.withUsername("test").password("{noop}test")
                .roles("ENDPOINT_ADMIN", "ADMIN", "TEST").build());
        manager.createUser(User.withUsername("root").password("{noop}root")
                .roles("ADMIN").build());
        return manager;
    }

}

permit all

@Configuration(proxyBeanMethods = false)
public class MySecurityConfiguration {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http.securityMatcher(EndpointRequest.toAnyEndpoint());
        http.authorizeHttpRequests((requests) -> requests.anyRequest().permitAll());
        return http.build();
    }

}

---

customize endpoint mapping

預設 http://localhost:8080/actuator 可取得所有暴露的 endpoints

ex:

{
    "_links": {
        "self": {
            "href": "http://localhost:8080/actuator",
            "templated": false
        },
        "health-path": {
            "href": "http://localhost:8080/actuator/health/{*path}",
            "templated": true
        },
        "health": {
            "href": "http://localhost:8080/actuator/health",
            "templated": false
        }
    }
}

可用以下設定禁用

management:
  endpoints:
    web:
      discovery:
        enabled: false

也可以修改 mapping，這樣要改用 http://localhost:8080/act/hth 取得 health

management:
  endpoints:
    web:
      base-path: /act
      path-mapping:
        health: hth

也可以修改 web port，不使用 service 的 web port。

management:
  server:
    port: 8088
    address: 127.0.0.1

把 port 改為 -1 等同 expose.exclude: "*"

management:
  server:
    port: -1

---

實作自訂 endpoint

endpoint 啟用時，會自動設定

heath endpoint 是用 HealthEndpointAutoConfiguration。 然後用 @Import 找到不同 web 類型的 endpoint class

health endpoint 是用 HealthEndpoint 類別實作的，該類別有 @Endpoint 註解，且要註冊為 Bean。支援以 @JmxEndpoint @WebEndpoint 暴露方式

以 @ReadOperation @WriteOperation @DeleteOperation 對應不同的 http method: GET/POST/DELETE

POST request Content-Type 只接受 application/vnd.spring-boot.actuator.v2+json, application/json

---

新增 User.java

package com.test.actuator;

import lombok.AllArgsConstructor;
import lombok.Data;

@Data
@AllArgsConstructor
public class User {
    private int id;
    private String name;
    private int age;

}

TestEndpoint.java

package com.test.actuator.endpoint;

import com.test.actuator.User;
import org.apache.commons.lang3.ObjectUtils;
import org.apache.commons.lang3.StringUtils;
import org.springframework.boot.actuate.endpoint.annotation.ReadOperation;
import org.springframework.boot.actuate.endpoint.annotation.Selector;
import org.springframework.boot.actuate.endpoint.annotation.WriteOperation;
import org.springframework.boot.actuate.endpoint.web.annotation.WebEndpoint;
import org.springframework.lang.Nullable;
import org.springframework.stereotype.Component;

@Component
@WebEndpoint(id = "test")
public class TestEndpoint {

    @ReadOperation
    public User getUser(@Selector Integer id) {
        return new User(id, "james", 18);
    }

    @WriteOperation
    public User updateUser(int id, @Nullable String name, @Nullable Integer age) {
        User user = getUser(id);
        user.setName(StringUtils.defaultIfBlank(name, user.getName()));
        user.setAge(ObjectUtils.defaultIfNull(age, user.getAge()));
        return user;
    }

}

注意要 expose endpoint

management:
  endpoints:
    web:
      exposure:
        include: "*"

瀏覽網址 http://localhost:8080/actuator/test/1

結果

{"id":1,"name":"james","age":18}

---

POST/DELETE 預設會回應 403，因為 spring boot 預設會打開 CSRF

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        return http.authorizeHttpRequests((authorize) -> {
                    authorize.requestMatchers("/").permitAll()
                            .requestMatchers(EndpointRequest.to("health")).hasRole("ENDPOINT_ADMIN")
                            .requestMatchers(EndpointRequest.toAnyEndpoint()).permitAll();
                })
                .csrf(csrf -> csrf.disable())
//                .csrf(csrf -> csrf.ignoringRequestMatchers(EndpointRequest.toAnyEndpoint()))
                .formLogin(withDefaults())
                .logout(logout -> logout.logoutUrl("/"))
                .build();
    }

enpoint 也支援 CORS 設定

management:
  endpoints:
    web:
      cors:
        allowed-origins: "https://test.com"
        allowed-methods: "GET,POST"

---

Observability

系統外部觀測正在運作的內部狀態的能力，spring boot 3 透過 Micrometer 提高可觀測性，支援 Micrometer 1.10+

引用可觀測 API，並自動設定 micrometer 追蹤，支援 Brave, OpenTelemetry, Zipkin, Wavefront

使用 micrometer API 完成觀測後，可將數據交給 Zipkin

---

Metrics

/actuator/metrics 指標，包含了 JVM, system, tomcat, Logger, Spring MVC...

預設不會 expose

瀏覽網址 http://localhost:8080/actuator/metrics 可查閱所有 metrics

http://localhost:8080/actuator/metrics/jvm.memory.max 就是取得 jvm.memory.max 的資訊

---

可自訂 metric

package com.test.actuator.metrics;

import io.micrometer.core.instrument.Gauge;
import io.micrometer.core.instrument.binder.MeterBinder;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;

@Configuration
public class MetricsConfig {

    @Bean
    public MeterBinder initDate(Environment env) {
        return (registry) -> Gauge.builder("init.date", this::date).register(registry);
    }

    @Bean
    public MeterBinder systemDate(Environment env) {
        return (registry) -> Gauge.builder("system.date", this::date).register(registry);
    }

    private Number date() {
        return 2024.11;
    }

}

網址 http://localhost:8080/actuator/metrics/init.date

結果

{
    "name":"init.date",
    "measurements":[
        {
            "statistic":"VALUE",
            "value":2024.11
        }
    ],
    "availableTags":[

    ]
}

Tracing

• 使用 OpenTelemetry 結合 Zipkin 或 Wavefront

• 使用 OpenZipkin Brave 結合 Zipkin 或 Wavefront

OpenTelemetry 可生成/收集/匯出觀測資料 metrics, logs, traces，他只會收集資料，分析跟展示要用其他軟體

Zipkin 是 Twitter 開源的分佈式追蹤系統，可收集解決服務的延遲問題的時間資料。如果 log 有 Trace ID，可直接展示。

       <!-- 將 Micrometer Observation API 橋接到 OpenTelemetry -->
        <dependency>
            <groupId>io.micrometer</groupId>
            <artifactId>micrometer-tracing-bridge-otel</artifactId>
        </dependency>

        <!-- 向 Zipkin 報告跟蹤資訊 -->
        <dependency>
            <groupId>io.opentelemetry</groupId>
            <artifactId>opentelemetry-exporter-zipkin</artifactId>
        </dependency>

採樣設定，預設為 0.1，也就是只採樣 10% 的 request

management:
  tracing:
    sampling:
      probability: 1.0

在 log 顯示 Trace ID, Span ID

logging:
  pattern:
    level: ${spring.application.name:},%X{traceId:-},%X{spanId:-}

Spring Boot Admin

GitHub - codecentric/spring-boot-admin: Admin UI for administration of spring boot applications

這個是社群開發的

• 有個 server 提供 Spring Boot Actuators UI

• 有個 client 註冊到 server，並能存取所有 actuator endpoints.

ref: Spring Boot Admin – Getting started

配置 Admin Server

<dependency>
    <groupId>de.codecentric</groupId>
    <artifactId>spring-boot-admin-starter-server</artifactId>
    <version>3.4.0</version>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

在 application 加上 @EnableAdminServer

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

配置 Client

<dependency>
    <groupId>de.codecentric</groupId>
    <artifactId>spring-boot-admin-starter-client</artifactId>
    <version>3.4.0</version>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
</dependency>

加上設定

spring:
  boot:
    admin:
      client:
        url: http://localhost:8080
management:
  endpoints:
    web:
      expose:
        include: '*'
  info:
    env:
      enabled: true

禁用所有安全機制

@Configuration
public static class SecurityPermitAllConfig {
    @Bean
    protected SecurityFilterChain filterChain(HttpSecurity http) {
        return http.authorizeHttpRequests((authorizeRequests) -> authorizeRequests.anyRequest().permitAll())
            .csrf().disable().build();
    }
}

網址 http://localhost:8088/

---

參考 Spring Boot Admin server notification 可設定通知

Prometheus

要在 pom.xml 加上 library

        <dependency>
            <groupId>io.micrometer</groupId>
            <artifactId>micrometer-registry-prometheus</artifactId>
            <version>${micrometer-registry-prometheus.version}</version>
        </dependency>

spring boot 就會提供 endpoint /actuator/prometheus 可 pull 資料

---

加上 libary

        <dependency>
            <groupId>io.micrometer</groupId>
            <artifactId>simpleclient_pushgateway</artifactId>
            <version>${simpleclient_pushgateway.version}</version>
        </dependency>

修改設定

management:
  prometheus:
    metrics:
      export:
        pushgateway:
          enabled: true

可 push 資料

---

Prometheus 通常結合 Grafana 使用

Spring Boot 3 打包

可用 jar, war, docker, GraalVM image 方式打包

jar

用 jar application 方式打包

<packaging>jar</packaging>

同時要加上

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

使用兩種指令打包，二選一

• mvn package

  打包到 target 目錄

• mvn install

  打包後，安裝到本地的 MAVEN repository

---

打包後，會產生兩個

• test-0.0.1-SNAPSHOT.jar

  這個可透過 java -jar test-0.0.1-SNAPSHOT.jar 啟動

• test-0.0.1-SNAPSHOT.jar.original

---

META-INF/MANIFEST.MF 內容為

Manifest-Version: 1.0
Created-By: Maven JAR Plugin 3.4.2
Build-Jdk-Spec: 17
Implementation-Title: test
Implementation-Version: 0.0.1-SNAPSHOT
Main-Class: org.springframework.boot.loader.launch.JarLauncher
Start-Class: com.test.test.TestApplication
Spring-Boot-Version: 3.4.0
Spring-Boot-Classes: BOOT-INF/classes/
Spring-Boot-Lib: BOOT-INF/lib/
Spring-Boot-Classpath-Index: BOOT-INF/classpath.idx
Spring-Boot-Layers-Index: BOOT-INF/layers.idx

另一個 test-0.0.1-SNAPSHOT.jar.original，無法直接啟動，只是一個 jar

---

war

要先產生一個繼承 SpringBootServletInitializer 抽象類別

package com.test.test;

import org.springframework.boot.builder.SpringApplicationBuilder;
import org.springframework.boot.web.servlet.support.SpringBootServletInitializer;

public class ServletInitializer extends SpringBootServletInitializer {

    @Override
    protected SpringApplicationBuilder configure(SpringApplicationBuilder application) {
        return application.sources(TestApplication.class);
    }

}

修改打包方式

<packaging>war</packaging>

排除 embedded tomcat

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-tomcat</artifactId>
            <scope>provided</scope>
        </dependency>

可同時支援 jar 跟 war

package com.test.test;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.builder.SpringApplicationBuilder;
import org.springframework.boot.web.servlet.support.SpringBootServletInitializer;

@SpringBootApplication
public class TestApplication extends SpringBootServletInitializer {

    @Override
    protected SpringApplicationBuilder configure(SpringApplicationBuilder builder) {
        return startBuilder(builder);
    }

    public static void main(String[] args) {
//        SpringApplication.run(TestApplication.class, args);
        startBuilder(new SpringApplicationBuilder()).run(args);
    }

    private static SpringApplicationBuilder startBuilder(SpringApplicationBuilder builder) {
        return builder.sources(TestApplication.class);
    }

}

build 會產生 test-0.0.1-SNAPSHOT.war，可以放在 tomcat 或是用 java -jar 啟動

---

啟動 application

使用 java 指令

java -jar test-0.0.1-SNAPSHOT-exec.war

直接啟動

在 pom.xml 要修改設定

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <executable>true</executable>
                </configuration>
            </plugin>
        </plugins>
    </build>

然侯就能直接運作

./test-0.0.1-SNAPSHOT-exec.war

note: 在不支援的 OS 要修改 pom.xml

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <classifier>exec</classifier>
                    <executable>true</executable>
                    <embeddedLaunchScript>...</embeddedLaunchScript>
                </configuration>
            </plugin>
        </plugins>
    </build>

系統 service

可用 init.d 或 systemd service 啟動

init.d

在 /etc/init.d 建立一個 link

sudo ln -s test-0.0.1-SNAPSHOT.war /etc/init.d/test

然後就能用 service 啟動

sudo service test start

systemd

在 /etc/systemd/system 目錄中，建立檔案 test.service

[Unit]
Description-test
After=syslog.target

[Service]
User=test
ExecStart=/home/test/test-0.0.1-SNAPSHOT.war
# process receive SIGTERM signal will return 128+15=143 exit status code
SuccessExitStatus=143

[Install]
WantedBy=multi-user.target

然後

sudo systemctl start test
sudo systemctl enable test

Docker

docker -v
docker version

以 Dockerfile 產生 image

FROM eclipse-temurin:17-jre
ARG JAR_FILE=target/*.jar
COPY ${JAR_FILE} application.jar
ENTRYPOINT ["java", "-Djava.security.egd=file:/dev/./urandom","-jar","/application.jar"]
EXPOSE 8080

eclipse-temurin 是 Eclipse 提供的 open JDK image

ARG 定義參數

用指令產生 image

docker build -t test/docker-all:1.0 .

-t tags，image 的 name:tags

啟動

docker run -dp 8080:8080 test/docker-all:1.0 

---

分層 image

定義分層的是 laryers.idx 檔案，內容為

- "dependencies":
  - "BOOT-INF/lib/"
- "spring-boot-loader":
  - "org/"
- "snapshot-dependencies":
- "application":
  - "BOOT-INF/classes/"
  - "BOOT-INF/classpath.idx"
  - "BOOT-INF/layers.idx"
  - "META-INF/"

一般會異動的只有 classes

建立新的 Dockerfile

FROM eclipse-temurin:17-jre as builder
WORKDIR application
ARG JAR_FILE=target/*-exec.jar
COPY ${JAR_FILE} application.jar
RUN java -Djarmode=layertools -jar application.jar extract

FROM eclipse-temurin:17-jre as builder
WORKDIR application
COPY --from-builder application/dependencies/ ./
COPY --from-builder application/spring-boot-loader/ ./
COPY --from-builder application/snapshot-dependencies/ ./
COPY --from-builder application/application/ ./
ENTRYPOINT ["java", "org.springframework.boot.loader.JarLauncher"]
EXPOSE 8081

注意 -Djarmode=layertools

layertools list

> java -Djarmode=layertools -jar test-0.0.1-SNAPSHOT.war list
dependencies
spring-boot-loader
snapshot-dependencies
application

產生 image

docker build -t test/docker-layer:1.0 .

分層建構不支援 executable jar，要修改 executable 設定

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <executable>false</executable>
                </configuration>
            </plugin>
        </plugins>
    </build>

Cloud Native Buildpacks

可透過 Maven/Gradle 產生 Cloud Native Buildpacks image

Cloud Native Buildpacks 是 2018 由 Pivotal, Heroku 發起，於10月加入Cloud Native沙盒，目標是要統一Buildpacks生態系。

修改 pom.xml

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <executions>
                    <execution>
                        <goals>
                            <goal>build-image</goal>
                        </goals>
                    </execution>
                </executions>
                <configuration>
                    <executable>false</executable>
                    <image>
                        <name>test/docker-cnb:${project.version}</name>
                    </image>
                </configuration>
            </plugin>
        </plugins>
    </build>

以指令產生

mvn clean package

也可以用 build-image target

mvn spring-boot:build-image

---

        <configuration>
          <executable>false</executable>
          <image>
            <name>test/docker-cnb:${project.version}</name>
            <pullPolicy>IF_NOT_PRESENT</pullPolicy>
          </image>
        </configuration>

可加上 pullPolicy

• ALWAYS

• IF_NOT_PRESENT: 不存在基礎 image 時才拉取

• NEVER

---

GraalVM image

Spring Boot 3.0 支援 GraalVM 22.3+, Native Build Tools Plugin 0.9.17+

GraalVM 是 2019 年 Oracle 發表的高性能，跨語言通用 VM，可提升 Java, Scala, Grooby, Kotlin 等基於 JVM 的 application。

GraalVM 有一個 Java 撰寫的高級 JIT compiler，借助 Truffle，可執行 Javascript, Ruby, Python

# Getting Started with Oracle GraalVM

產生 native-image

javac HelloWorld.java
native-image HelloWorld
./helloworld
Hello, World!

---

GraalVM applicaiton 跟傳統 application 的差異

對於 Java applicaiton，GraalVM 提供兩種運作方法

• 在 HotSpot VM 上使用 Graal 的 JIT compiler，一邊編譯，一邊運作

• 以 AOT 編譯的 GraalVM 原生 image 可執行檔案運作，是靜態預先編譯

GraalVM applcation 的差別

• GraalVM image 會進行靜態分析

• 產生 image 時，無法執行到的 code 會被刪除，不會成為可執行檔案的一部分

• GraalVM 不能直接偵測 code 的動態元素，ex: reflection, resource, 序列化, 動態代理，必須提前宣告設定

• 應用的 classpath 路徑是固定的，不能修改

• 不支援 bean 的延遲載入

• 某些地方不完全相容傳統的 java app

---

spring boot 產生 image 時

• classpath 固定，無法變更

• bean 不能被修改，不支援 @Profile，@ConditionalOnProperty

Spring AOT 在產生 image 時，同時會產生

• Java source code

• byte code

• GraalVM 相關 JSON 描述檔案，包含

  • resource-config.json Resource hints

  • reflection.config.json Reflection hints

  • serialization-config.json Serialization hints

  • proxy-config.json Java Proxy hints

  • jni-config.json JNI hints

---

從 https://start.spring.io/ 產生的 project，增加 Graal VM Nartive Support，maven pom.xml 裡面就包含了 native, native test 兩個 profiles

        <plugins>
            <plugin>
                <groupId>org.graalvm.buildtools</groupId>
                <artifactId>native-maven-plugin</artifactId>
            </plugin>
        </plugins>

---

使用 maven 產生 image

mvn -Pnative spring-boot:build-image

可用 docker 執行

docker run --rm -p 8080:8080 docker.io/library/spring-boot-graalvm:1.0

---

也可以安裝 GraalVM Native Build Tools

sdk install java 23.0.1-graal
sdk use java 23.0.1-graal

用 maven

mvn -Pnative native:compile

會產生

• spring-boot-graalvm: app 可執行檔案

• spring-boot-graalvm.build_artifacts.txt: 說明 txt

Spring Boot 3 unit test

libary 有兩個

• spring-boot-test: 測試核心功能

• spring-boot-test-autoconfigure: 測試的自動設定

spring-boot-starter-test 是集合

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>

測試還包含其他 library

• JUnit 5

• AssertJ

• Hamcrest

• Mockito

• JSONassert

• JsonPath

---

spring 提供一個 @SpringBootTest annotation，裡面有一個 webEnvironment 環境變數，支援以下設定

• MOCK (default)

  載入一個 WebApplicationContext 並提供 Mock Web Environment。不會啟動內嵌的 web server，並可以結合 @AutoConfigureMockMvcor @AutoConfigureWebTestClient 進行 MOCK 測試

• RANDOM_PORT

  載入一個 WebApplicationContext，提供一個真實的 web environment，隨機 port

• DEFINED_PORT

  載入一個 WebApplicationContext，提供一個真實的 web environment，指定 port，預設 8080

• NONE

  載入一個 WebApplicationContext，不提供 web environment

---

Spring MVC 測試

MvcTests.java

package com.test.test;

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.test.web.client.TestRestTemplate;

import java.util.HashMap;
import java.util.Map;

import static org.assertj.core.api.Assertions.assertThat;

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
public class MvcTests {

    @Test
    public void getUserTest(@Autowired TestRestTemplate testRestTemplate) {
        Map<String, String> multiValueMap = new HashMap<>();
        multiValueMap.put("username", "test1");
        Result result = testRestTemplate.getForObject("/user/get?username={username}",
                Result.class, multiValueMap);
        assertThat(result.getCode()).isEqualTo(0);
        assertThat(result.getMsg()).isEqualTo("ok");
    }

}

呼叫 /user/test，檢查回傳的資料是否正確

從 log 可發現 tomcat 運作在另一個 port

Tomcat started on port 53594 (http) with context path '/'

---

MOCK 測試

package com.test.test;

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.request.MockMvcRequestBuilders;

import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.content;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

@SpringBootTest
@AutoConfigureMockMvc
class MockMvcTests {

    @Test
    public void getUserTest(@Autowired MockMvc mvc) throws Exception {
        mvc.perform(MockMvcRequestBuilders.get("/user/get?username={username}", "test"))
                .andExpect(status().isOk())
                .andExpect(content().string("{\"code\":0,\"msg\":\"ok\",\"data\":\"test\"}"));
    }

}

在class 上面增加 @AutoConfigureMockMvc ，然後在 method 上加上 @Autowired MockMvc mvc 就可進行 MOCK 測試。

從 log 發現並沒有真的啟動一個 web server

---

MOCK 元件測試

package com.test.test;

import com.test.test.service.UserService;
import org.junit.jupiter.api.Test;
import org.mockito.BDDMockito;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.bean.override.mockito.MockitoBean;

import static org.assertj.core.api.Assertions.assertThat;

@SpringBootTest
class MockBeanTests {

//    @Autowired
//    private UserService userService;

    @MockitoBean
    private UserService userService;

    @Test
    public void countAllUsers() {
        BDDMockito.given(this.userService.countAllUsers()).willReturn(88);
        assertThat(this.userService.countAllUsers()).isEqualTo(88);
    }

}

@MockitoBean 代表該變數是被 Mock 覆蓋

這邊透過 BDDMockito 模擬 countAllUsers 回傳結果

---

JSON 測試

spring 提供各種技術元件的單元測試

想要測試 JSON，可使用 JsonTestersAutoConfiguration，只需要在測試類別加上 @JsonTest

先新增一個檔案 test/resources/jack.json

{"id":10001, "name":"Jack", "birthday": "2000-10-08 21:00:00"}

User POJO

package com.test.test;

import com.fasterxml.jackson.annotation.JsonFormat;
import lombok.AllArgsConstructor;
import lombok.Data;

import java.time.LocalDateTime;

@Data
@AllArgsConstructor
public class User {
    private long id;
    private String name;
    @JsonFormat(timezone = "GMT+8", pattern = "yyyy-MM-dd HH:mm:ss")
    private LocalDateTime birthday;

}

JsonTests.java

package com.test.test;

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.json.JsonTest;
import org.springframework.boot.test.json.JacksonTester;

import java.time.LocalDateTime;

import static org.assertj.core.api.Assertions.assertThat;

@JsonTest
class JsonTests {

    @Autowired
    private JacksonTester<User> json;

    @Test
    void serialize() throws Exception {
        User user = new User(10001L, "Jack",
                LocalDateTime.of(2000, 10, 8, 21, 0, 0));
        assertThat(this.json.write(user)).isEqualToJson("/jack.json");
        assertThat(this.json.write(user)).hasJsonPathStringValue("@.name");
        assertThat(this.json.write(user)).
                extractingJsonPathStringValue("@.name").isEqualTo("Jack");
    }

    @Test
    void deserialize() throws Exception {
        String content = "{\"id\":10002, \"name\":\"Petty\", \"birthday\": \"2025-01-01 01:01:00\"}";
        assertThat(this.json.parse(content))
                .isEqualTo(new User(10002L, "Petty",
                        LocalDateTime.of(2025, 1, 1, 1, 1, 0)));
        assertThat(this.json.parseObject(content).getName()).isEqualTo("Petty");
    }

}

Spring Boot 3 test

斷點測試

用 main 直接啟動 Debug mode

在啟動 application 時，用 Debug mode 方式啟動。當程式到達斷點時，會自動暫停

用 maven plugin

使用 main 啟動 debug mode 的缺點是，無法使用 maven plugins。

使用 spring boot maven plugin 啟動 application 會 fork process 執行，故無法像 main 的方式一樣，直接 debug。需要用遠端測試的方法。

首先是需要在 spring boot maven plugin 中，設定 jvmArguments 測試參數，並啟動 application，然後新增一個遠端測試

啟動測試模式

有兩種方法

• 在 plugin 設定中指定測試模式的 jvmArguments

      <build>
          <plugins>
              <plugin>
                  <groupId>org.springframework.boot</groupId>
                  <artifactId>spring-boot-maven-plugin</artifactId>
                  <configuration>
                      <jvmArguments>
                          -Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005
                      </jvmArguments>
                  </configuration>
              </plugin>
          </plugins>
      </build>

• 使用 mvn 啟動時，指定測試參數

  mvn spring-boot:run -Dspring-boot.run.jvmArguments="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005"

啟動後，會在 console 最後面看到

> mvn spring-boot:run
[INFO] --- spring-boot-maven-plugin:3.4.0:run (default-cli) @ test ---
[INFO] Attaching agents: []
Listening for transport dt_socket at address: 5005

遠端測試

透過 IDE 建立 Remote test application

連接後，剛剛的 mvn 才會完成啟動，出現 application 的 log

Connected to the target VM, address: 'localhost:5005', transport: 'socket'

JVM remote debug 要處理斷點會比較麻煩

---

開發者工具

spring boot 提供 devtools，功能可自動禁用 cache，支援 application 自動重啟，即時 reload

只要引用 libary 即可

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-devtools</artifactId>
            <optional>true</optional>
        </dependency>

optional 代表只會在本專案/子專案中使用，不會傳遞到引用該專案的project

devtools 是在開發時使用，打包時 spring boot 預設不會把 devtools 包裝進去。可修改此設定

        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <excludeDevtools>false</excludeDevtools>
                </configuration>
            </plugin>
        </plugins>

並在啟動時，加上 -Dspring.devtools.restart.enabled=true 啟用

但不建議將 devtools 打包進去

---

預設值

Name	Default Value
server.error.include-binding-errors	always
server.error.include-message	always
server.error.include-stacktrace	always
server.servlet.jsp.init-parameters.development	true
server.servlet.session.persistent	true
spring.docker.compose.readiness.wait	only-if-started
spring.freemarker.cache	false
spring.graphql.graphiql.enabled	true
spring.groovy.template.cache	false
spring.h2.console.enabled	true
spring.mustache.servlet.cache	false
spring.mvc.log-resolved-exception	true
spring.reactor.netty.shutdown-quiet-period	0s
spring.template.provider.cache	false
spring.thymeleaf.cache	false
spring.web.resources.cache.period	0
spring.web.resources.chain.cache	false

devtools 預設禁用 cache，因為開發階段禁用 cache，較容易排除問題

可透過設定修改

spring:
  devtools:
    add-properties: false

---

自動 restart

devtools 會監控檔案，發生變更就會快速自動 restart。這邊使用兩個 class loader

• base classloader

  基本不會變更的檔案，ex: 3rd party jar

• restart classloader

  application 相關檔案

restart 時，base classloader 不需要異動，只需要重建一個 restart classloader

但要注意：AspectJ AOP programming 不支援 auto restart

---

觸發機制

• Eclipse: 修改 save 後就會觸發

• IntelliJ IDEA: 要重新 build 才會觸發

• build tool: 在 IDE 使用 mvn compile/grdle build 會觸發

---

修改時頻繁 restart，會消耗很多資源

可將 IDE 改為手動編譯，或是指定一個觸發檔案

spring:
  devtools:
    restart:
      trigger-file: .reloadtrigger

只有在 .reloadtrigger 檔案被修改時，才會自動 restart

---

IDE 有支援自動產生 trigger file

然後在 application 有個 update 按鈕

此方法只適用於用 main 啟動的 spring application，不適用 mvn

---

排除資源

預設狀況下以下資源目錄不會觸發 restart，但會觸發自動 reload

• /META-INF/maven

• /META-INF/resources

• /resources

• /static

• /public

• /templates

可修改此設定

spring:
  devtools:
    restart:
      exclude: static/**,public/**
      # 保留預設，增加其他目錄
      # additional-exclude:

---

禁用 log

application 自動 restart 都會列印 log，可用以下方式關閉

spring:
  devtools:
    restart:
      log-confition-evaluation-delta: false

禁用 auto restart

spring:
  devtools:
    restart:
      enabled: false

---

auto reload

browser 要安裝 LiveReload plugin，並打開 devtool 的 auto reload 功能

devtools 內建一個 LiveReload server 在 port 35729

預設狀況下以下資源目錄不會觸發 restart，但會觸發自動 reload

• /META-INF/maven

• /META-INF/resources

• /resources

• /static

• /public

• /templates

可關閉 auto reload

spring:
  devtools:
    livereload:
      enabled: false

---

global 設定

在 $HOME/.config/spring-boot 目錄中，設定檔名為 spring-boot-devtools。支援 properties 或 yaml

spring-boot-devtools.properties

spring-boot-devtools.yaml

spring-boot-devtools.yml

$HOME 預設是 user 主目錄，可用以下方式修改

• 設定 SPRING_DEVTOOLS_HOME 環境變數

• 設定 spring-devtools.home 系統參數

example: spring-boot-devtools.yml

spring:
  devtools:
    restart:
      log-condition-evaluation-delta: false
      trigger-file: ".reloadtrigger"

Spring Boot 支援

• JMS

  Java message Service，支援 JmsTemplate

• AMQP

  Advanced Message Queue Protocol

  為 RabbitMQ 提供 RabbitTemplate

• Apache Kafka

  KafkaTemplate

• STOMP

  Simple Text-Oriented Message Protocol

org.springframework.boot.autoconfigure.AutoConfiguration.imports

自動設定類別

• JmsAutoConfiguration

• ArtemisAutoConfiguration

• RabbitAutoConfiguration

• KafkaAutoConfiguration

---

ActiveMQ

JMS 主流 ActiveMQ, RocketMQ

JMS 有兩個版本

• JMS 1.1

• JMS 2.0

ActiveMQ 有兩個主要版本

• ActiveMQ Classic

  ActiveMQ 5.x 以前

  JMS 1.1

• ActiveMQ Artemis

  ActiveMQ 6.x+

  JMS 2.0

---

下載 apache-artemis-2.38.0-bin.tar.gz

tar zxvf apache-artemis-2.38.0-bin.tar.gz
mkdir -p /root/download/artemis/data/
apache-artemis-2.38.0/bin/artemis create mybroker

建立 broker

# ../apache-artemis-2.38.0/bin/artemis create mybroker
Creating ActiveMQ Artemis instance at: /root/download/artemis/data/mybroker

--user:
What is the default username?
admin

--password: is mandatory with this configuration:
What is the default password?


--allow-anonymous | --require-login:
Allow anonymous access?, valid values are Y, N, True, False
n

Auto tuning journal ...
done! Your system can make 7.58 writes per millisecond, your journal-buffer-timeout will be 132000

You can now start the broker by executing:

   "/root/download/artemis/data/mybroker/bin/artemis" run

Or you can run the broker in the background using:

   "/root/download/artemis/data/mybroker/bin/artemis-service" start

修改 /root/download/artemis/data/mybroker/etc/bootstrap.xml 的 artemis uri，由 localhost 改為 0.0.0.0

   <web path="web" rootRedirectLocation="console">
       <binding name="artemis" uri="http://0.0.0.0:8161">
           <app name="branding" url="activemq-branding" war="activemq-branding.war"/>
           <app name="plugin" url="artemis-plugin" war="artemis-plugin.war"/>
           <app name="console" url="console" war="console.war"/>
       </binding>
   </web>

啟動後，可瀏覽 web console http://192.168.1.89:8161/

---

pom.xml 增加 spring-boot-starter-artemis

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-artemis</artifactId>
        </dependency>

org.springframework.boot.autoconfigure.AutoConfiguration.imports

自動設定類別

• JmsAutoConfiguration

• JndiConnectionFactoryAutoConfiguration

• ArtemisAutoConfiguration

只要設定 spring.jms.* 及 spring.artemis.*

spring:
  jms:
    cache:
      enabled: true
      session-cache-size: 5 # default: 1
  artemis:
    mode: native
    broker-url: tcp://localhost:61616
    user: admin
    password: password

也可以加上 pool

spring:
  jms:
    cache:
      enabled: true
      session-cache-size: 5 # default: 1
  artemis:
    mode: native
    broker-url: tcp://localhost:61616
    user: admin
    password: password
    pool:
      enabled: true # default: false
      max-connections: 50 # default: 1
      idle-timeout: 5s # default: 30s
      max-sessions-per-connection: 100 # default: 500

還須要加上 library

        <dependency>
            <groupId>org.messaginghub</groupId>
            <artifactId>pooled-jms</artifactId>
        </dependency>

補上 web library

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <scope>provided</scope>
        </dependency>

---

MsgController.java

package com.test.artemis;

import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.jms.annotation.JmsListener;
import org.springframework.jms.core.JmsTemplate;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RequiredArgsConstructor
@RestController
@Slf4j
public class MsgController {

    private final JmsTemplate jmsTemplate;

    /**
     * send message
     * @param msg
     * @return
     */
    @RequestMapping("/send")
    public String sendMsg(@RequestParam("msg") String msg) {
        jmsTemplate.convertAndSend("test-queue", msg);
        return "message is sent";
    }

    /**
     * receive message
     * @param msg
     */
    @JmsListener(destination = "test-queue")
    public void receiveMsg(String msg) {
        log.info("receive ActiveMQ message：{}", msg);
    }

}

測試網址

http://localhost:8080/send?msg=test1234

console 可看到

receive ActiveMQ message：test1234

Spring Boot 3 amqp

RabbitMQ 重要元件有

• ConnectionFactory

• Channel: 發送訊息

• Exchange: 交換器，分發訊息

• Queue: 儲存 producer 發送的訊息

• RoutingKey: exchange 把 producer 的訊息寫入不同的 queue

• BindingKey: exchange 綁定到不同的 queue

exchange 支援的訊息模式：

• direct

  預設 路由模式。發送訊息到指定的 Routing Key，寫入不同的 queue

• fanout

  廣播模式。將訊息送到綁定的所有 queues 裡面。性能最好，最常用

• headers

  匹配模式。根據訊息的 header 跟 queue 的參數匹配。性能差，少用

• topic

  匹配模式。可使用 * 匹配

---

rabbitmq cli 設定新增 user

rabbitmqctl add_user admin password
rabbitmqctl set_permissions -p "/" admin ".*" ".*" ".*"
rabbitmqctl set_user_tags admin administrator
rabbitmqctl delete_user guest
rabbitmqctl list_users

---

pom.xml

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-amqp</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <scope>provided</scope>
        </dependency>

---

org.springframework.boot.autoconfigure.AutoConfiguration.imports 註冊

RabbitAutoConfiguration。參數綁定類別為 RabbitProperties。參數為 spring.rabbitmq.*

application.yml

spring:
  rabbitmq:
    host: localhost
    port: 5672
    username: admin
    password: password

也可以設定為 uri 形式

spring:
  rabbitmq:
    addresses: "amqp://admin:password@localhost"

---

MsgController.java

package com.test.amqp;

import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.amqp.rabbit.annotation.RabbitListener;
import org.springframework.amqp.rabbit.core.RabbitTemplate;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RequiredArgsConstructor
@RestController
@Slf4j
public class MsgController {

    private final RabbitTemplate rabbitTemplate;

    /**
     * send message: Direct mode
     * @param msg
     * @return
     */
    @RequestMapping("/send")
    public String sendMsg(@RequestParam("msg") String msg) {
        rabbitTemplate.convertAndSend("test-direct-exchange",
                "test-direct-routing-key", msg);
        return "message sent";
    }

    /**
     * receive message: Direct Mode
     * @param msg
     */
    @RabbitListener(queues = "test-direct-queue")
    public void receiveMsg(String msg) {
        log.info("message received：{}", msg);
    }

}

RabbitMQ 無法自動產生 queue, exchange。除了能在 web console 設定，也可以透過程式設定

package com.test.amqp;

import org.springframework.amqp.core.Binding;
import org.springframework.amqp.core.BindingBuilder;
import org.springframework.amqp.core.DirectExchange;
import org.springframework.amqp.core.Queue;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class RabbitMQConfig {

    /**
     * create queue: Direct Mode
     * @return
     */
    @Bean
    public Queue testDirectQueue() {
        return new Queue("test-direct-queue");
    }

    /**
     * create exchange: Direct Mode
     * @return
     */
    @Bean
    public DirectExchange TestDirectExchange() {
        return new DirectExchange("test-direct-exchange");
    }

    /**
     * create routing key: Direct Mode
     * @param testDirectQueue
     * @return
     */
    @Bean
    public Binding testDirectBinding(Queue testDirectQueue) {
        return BindingBuilder.bind(testDirectQueue)
                .to(TestDirectExchange()).with("test-direct-routing-key");
    }

}

---

測試

http://localhost:8080/send?msg=test1234

Spring Boot 3 Cache

spring 提供對 cache 的 API 介面

• org.springframework.cache.Cache

• org.springframework.cache.CacheManager

如果 application 沒有註冊 CacheManager 或 CacheResolver，spring 會依照以下順序檢測 cache component

Generic -> JCache (JSR-107) (EhCache3, Hazelcast, Infinispan..) -> Hazelcast -> Infinispan -> Couchbase -> Redis -> Caffeine -> Cache2k -> Simple

org.springframework.boot.autoconfigure.AutoConfiguration.imports 有註冊自動設定類別

自動設定類別為 CacheAutoConfiguration，參數綁定類別為 CacheProperties

設定參數 spring.cache.*

pom.xml

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-cache</artifactId>
        </dependency>

                <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

application.yml

spring:
  cache:
    type: none
    # none 代表禁用 cache
    # type: redis

type 可設定為 COUCHBASE/GENERIC/REDIS/HAZELCAST/CACHE2K/CAFFEINE/JCACHE/INFINISPAN/NONE/SIMPLE

---

預設簡單 cache

如果沒有設定任何 cache 元件，就是使用 Simple，也就是 thread-safe 的 ConcurrentHashMap

pom.xml 加上 web

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

application 要加上 @EnableCaching

@EnableCaching
@SpringBootApplication
public class CacheApplication {

    public static void main(String[] args) {
        SpringApplication.run(CacheApplication.class, args);
    }

}

先建立一個兩數相乘的 cache service

CacheService.java

package com.test.cache;

import lombok.extern.slf4j.Slf4j;
import org.springframework.cache.annotation.Cacheable;
import org.springframework.stereotype.Service;

@Slf4j
@Service
public class CacheService {

    @Cacheable("calc")
    public int multiply(int a, int b) {
        int c = a * b;
        log.info("{} * {} = {}", a, b, c);
        return c;
    }

}

@Cacheable 代表該 method 使用 cache，這是用 AOP 的方法做的

一個測試用的 web service

package com.test.cache;

import lombok.RequiredArgsConstructor;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RequiredArgsConstructor
@RestController
public class CacheController {

    private final CacheService cacheService;

    @RequestMapping("/multiply")
    public int multiply(@RequestParam("a") int a,
                        @RequestParam("b") int b) {
        return cacheService.multiply(a, b);
    }

}

測試網址 http://localhost:8080/multiply?a=2&b=3

重複多測試幾次，console log 上面都還是只有一行 log。代表重複的參數，會直接從 cache 取得結果，不會進入 service

com.test.cache.CacheService              : 2 * 3 = 6

---

Redis Cache

pom.xml 加上 redis

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-redis</artifactId>
        </dependency>

application.yml

spring:
  data:
    redis:
      host: localhost
      port: 6379
      database: 0
      password: password

redis-cli

# redis-cli -a password
Warning: Using a password with '-a' or '-u' option on the command line interface may not be safe.
127.0.0.1:6379> keys *
1) "calc::SimpleKey [2, 3]"
127.0.0.1:6379> get "calc::SimpleKey [2, 3]"
"\xac\xed\x00\x05sr\x00\x11java.lang.Integer\x12\xe2\xa0\xa4\xf7\x81\x878\x02\x00\x01I\x00\x05valuexr\x00\x10java.lang.Number\x86\xac\x95\x1d\x0b\x94\xe0\x8b\x02\x00\x00xp\x00\x00\x00\x06"

---

可在建立 cache 名稱，time-to-live 代表只存放 10s

spring:
  data:
    redis:
      host: localhost
      port: 6379
      database: 0
      password: password
  cache:
    type: redis
    cache-names: "calc,test"
    redis:
      time-to-live: "10s"

針對不同 cache 設定不同規則，可透過 RedisCacheManagerBuilderCustomizer

package com.test.cache;

import org.springframework.boot.autoconfigure.cache.RedisCacheManagerBuilderCustomizer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.data.redis.cache.RedisCacheConfiguration;

import java.time.Duration;

@Configuration
public class CacheConfiguration {

    /**
     * 比 application.yml 的設定內容優先權高
     * @return
     */
    @Bean
    public RedisCacheManagerBuilderCustomizer myRedisCacheManagerBuilderCustomizer() {
        return (builder) -> builder
                .withCacheConfiguration("calc", RedisCacheConfiguration
                        .defaultCacheConfig().entryTtl(Duration.ofSeconds(5)))
                .withCacheConfiguration("test", RedisCacheConfiguration
                        .defaultCacheConfig().entryTtl(Duration.ofMinutes(10)));

    }

}

網址 http://localhost:8080/multiply?a=2&b=3

calc, test 兩個 redis cache 都有資料

# redis-cli -a password -n test
Warning: Using a password with '-a' or '-u' option on the command line interface may not be safe.
127.0.0.1:6379> keys *
1) "calc::SimpleKey [2, 3]"

# redis-cli -a password -n calc
Warning: Using a password with '-a' or '-u' option on the command line interface may not be safe.
127.0.0.1:6379> keys *
1) "calc::SimpleKey [2, 3]"

Spring Boot 3 quartz

簡單的任務可用 spring task scheduler，複雜的要改用 quartz

pom.xml 要加上 spring-boot-starter-quartz

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-quartz</artifactId>
        </dependency>

自動設定類別是 QuartzAutoConfiguration，透過註冊的 SchedulerFactoryBean 就能產生 Scheduler。參數綁定類別為 QuartzProperties，參數為 spring.quartz.*

產生 task

只要繼承 QuartzJobBean，實作 executeInternal，就可以產生 quartz 的 Job

SimpleTask.java

package com.test.quartz;

import lombok.extern.slf4j.Slf4j;
import org.quartz.JobExecutionContext;
import org.springframework.scheduling.quartz.QuartzJobBean;

@Slf4j
public class SimpleTask extends QuartzJobBean {

    @Override
    protected void executeInternal(JobExecutionContext context) {
        log.info("simple task");
    }

}

設定

• JobDetail

• Calendar: 指定/排除特定時間

• Trigger

TaskConfig.java

package com.test.quartz;

import jakarta.annotation.PostConstruct;
import lombok.RequiredArgsConstructor;
import org.quartz.*;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.scheduling.quartz.SchedulerFactoryBean;

@RequiredArgsConstructor
@Configuration
public class TaskConfig {

    public static final String SIMPLE_TASK = "simple-task";
//    private final SchedulerFactoryBean schedulerFactoryBean;
//
//    @PostConstruct
//    public void init() throws SchedulerException {
//        Scheduler scheduler = schedulerFactoryBean.getScheduler();
//        boolean exists = scheduler.checkExists(JobKey.jobKey(SIMPLE_TASK));
//        if (!exists) {
//            scheduler.scheduleJob(simpleTask(), simpleTaskTrigger());
//        }
//    }

    @Bean
    public JobDetail simpleTask() {
        return JobBuilder.newJob(SimpleTask.class)
                .withIdentity(SIMPLE_TASK)
                .withDescription("simple-task")
                .storeDurably()
                .build();
    }

    @Bean
    public Trigger simpleTaskTrigger() {
        CronScheduleBuilder cronScheduleBuilder = CronScheduleBuilder.cronSchedule("0/3 * * * * ? *");
        return TriggerBuilder.newTrigger()
                .withIdentity("simple-task-trigger")
                .forJob(simpleTask())
                .withSchedule(cronScheduleBuilder)
                .build();
    }

}

cron expression 多了最後一個 [<year>] 可以不填寫

<second> <minute> <hour> <day of month> <month> <day of week> [<year>]

ex:

"0/3 * * * * ? 2025-2030" 代表 2025-2030 每 3s 執行一次

啟動後，會看到

org.quartz.core.QuartzScheduler          : Scheduler meta-data: Quartz Scheduler (v2.3.2) 'quartzScheduler' with instanceId 'NON_CLUSTERED'
  Scheduler class: 'org.quartz.core.QuartzScheduler' - running locally.
  NOT STARTED.
  Currently in standby mode.
  Number of jobs executed: 0
  Using thread pool 'org.quartz.simpl.SimpleThreadPool' - with 10 threads.
  Using job-store 'org.quartz.simpl.RAMJobStore' - which does not support persistence. and is not clustered.

設定參數

以下代表將 thread 設定為 5 個

spring:
  quartz:
    properties:
      org:
        quartz:
          threadPool:
            threadCount: 5

persistence

quartz 支援兩種 persistence 方式

• memory

  預設。每次停止 application 就會把資料丟掉

• JDBC

pom.xml 加上 JDBC

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-jdbc</artifactId>
        </dependency>
        <dependency>
            <groupId>com.mysql</groupId>
            <artifactId>mysql-connector-j</artifactId>
        </dependency>

application.yml

spring:
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://localhost:3306/testweb
    username: root
    password: password
  quartz:
    job-store-type: jdbc
    jdbc:
      initialize-schema: always # always
    overwrite-existing-jobs: true
    properties:
      org:
        quartz:
          threadPool:
            threadCount: 5

initialize-schema 有三種

• ALWAYS: 每一次都會重建

• EMBEDDED: 只初始化嵌入式 DB

• NEVER

---

動態維護 task

如果 task 太多，會有大量設定的 code，可改用 SchedulerFactoryBean 動態 add/remove task

package com.test.quartz;

import jakarta.annotation.PostConstruct;
import lombok.RequiredArgsConstructor;
import org.quartz.*;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.scheduling.quartz.SchedulerFactoryBean;

@RequiredArgsConstructor
@Configuration
public class TaskConfig {

    public static final String SIMPLE_TASK = "simple-task";
    private final SchedulerFactoryBean schedulerFactoryBean;

    @PostConstruct
    public void init() throws SchedulerException {
        Scheduler scheduler = schedulerFactoryBean.getScheduler();
        boolean exists = scheduler.checkExists(JobKey.jobKey(SIMPLE_TASK));
        if (!exists) {
            scheduler.scheduleJob(simpleTask(), simpleTaskTrigger());
        }
    }

//    @Bean
    public JobDetail simpleTask() {
        return JobBuilder.newJob(SimpleTask.class)
                .withIdentity(SIMPLE_TASK)
                .withDescription("simple-task")
                .storeDurably()
                .build();
    }

//    @Bean
    public Trigger simpleTaskTrigger() {
        CronScheduleBuilder cronScheduleBuilder = CronScheduleBuilder.cronSchedule("0/3 * * * * ? *");
        return TriggerBuilder.newTrigger()
                .withIdentity("simple-task-trigger")
                .forJob(simpleTask())
                .withSchedule(cronScheduleBuilder)
                .build();
    }

}

Spring Boot 3 Scheduler

spring 的 scheduler task 主要需要 spring-context library，因為任何一個 spring boot start 都有包含 spring-context，所以都有支援 scheduler。

spring 提供自動設定類別

• TaskExecutionAutoConfiguration

• TaskSchedulingAutoConfiguration

註冊在 org.springframework.boot.autoconfigure.AutoConfiguration.imports 檔案中

如果 context 裡面沒有任何 Executor instance，就會自動註冊一個預設的 ThreadPoolTaskExecutor，該類別是使用 java.util.concurrent.Executor interface 實作自己的 task executor。同時註冊了一個 TaskExecutorBuilder instance，用來實作自訂的 task executor thread pool。

參數綁定類別是 TaskExecutionProperties

參數是 spring.task.execution.*

---

如果 context 裡面沒有任何一個 instance

• SchedulerConfigurer

  org.springframework.scheduling.annotation

• TaskScheduler

  org.springframework.scheduling

• SchedulerdExecutorService

  java.util.concurrent

就會自動註冊一個 ThreadPoolTaskScheduler instance。

可以註冊一個 TaskSchedulerBuilder instance，參數對應綁定類別是 TaskSchedulingProperties。參數是 spring.task.scheduling.*

---

• thread size < core thread size(coreSize)

  • 產生新的 thread 執行 task

• thread size = core thread size(coreSize) 且 queueCapacity is not full

  • 將 task 放入 queue

• thread size = core thread size(coreSize) 且 queueCapacity is full 且 thread size < max thread size (maxSize)

  • 產生新的 thread 執行 task

• coreSize, queueCapacity, maxSize 都滿了

  • 拒絕執行 task

  • 預設為 AbortPolicy (ref: ExecutorConfigurationSupport)

• thread 空閒時間到達 keepAlive 時

  • 刪除 thread

  • 預設只會刪除 core thread 以外的 threads

  • allowCoreThreadTimeout 可控制是否要刪除 core thread

---

spring task 使用起來比 quartz 簡單

先在 application 加上 @EnableScheduling

@EnableScheduling
@SpringBootApplication
public class TaskApplication {

    public static void main(String[] args) {
        SpringApplication.run(TaskApplication.class, args);
    }

}

• @EnableScheduling

  表示啟用 scheduling，會引用 SchedulingConfiguraiton 自動設定，這是透過註冊 ScheduledAnnotationBeanPostProcessor instance 實現

• @EnableAsync

  啟用 task 非同步運作，這是引用 AsyncConfigurationSelector，根據不同的 AOP 選擇不同的設定類別

這兩個都屬於 spring-context 的 annotation，不需要其他 library

---

SimpleTask

SmpleTask.java

package com.test.task;

import lombok.extern.slf4j.Slf4j;
import org.springframework.scheduling.annotation.Async;
import org.springframework.scheduling.annotation.Scheduled;
import org.springframework.stereotype.Component;

@Slf4j
@Component
public class SimpleTask {

    @Async
    @Scheduled(cron = "*/3 * * * * *")
    public void printTask() {
        log.info("SimpleTask is working ...");
    }

}

執行時，固定會以 "scheduling-1" 這個 thread 執行

[   scheduling-1] com.test.task.SimpleTask                 : SimpleTask is working ...

沒有用到 ThreadPoolTaskExecutor

---

修改 application，加上 @EnableAsync，才會使用到 ThreadPoolTaskExecutor

@EnableScheduling
@EnableAsync
@SpringBootApplication
public class TaskApplication {

    public static void main(String[] args) {
        SpringApplication.run(TaskApplication.class, args);
    }

}

執行結果，會是 task-1 ~ task-8，然後一直重複。 ThreadPoolTaskExecutor 預設有 8 個 coreThread

[         task-1] com.test.task.SimpleTask                 : SimpleTask is working ...
[         task-2] com.test.task.SimpleTask                 : SimpleTask is working ...

cron

<second> <minute> <hour> <day of month> <month> <day of week>

• second: 0~59

• minute: 0~59

• hour: 0~23

• day of month: 1~31

• month: 1~12 或 JAN ~ DEC

• day of week: 0~7，0 代表週日，或是 MON ~ SUN

example:

cron expression	desc
*/3 * * * * *	每 3s 執行一次
0 0 * * * *	每小時 0分 0 秒執行一次
0 0 9~16 * * *	每天 9 ~ 16 點整點執行一次
0 0 9,16 * * *	每天 9,16 點執行一次
0 0/30 9-16 * * *	每天 9 ~ 16 點，每 30 分執行一次

支援用以下的寫法替代

• @yearly 等同 0 0 0 1 1 *

• @monthly

• @weekly

• @daily

• @hourly

cron expression 不支援年

---

自訂 thread pool

修改系統設定參數

application.yml

spring:
  task:
    execution:
      pool:
        # core thread size
        coreSize: 5
        # max thread size
        maxSize: 10
        # max queue size
        queueCapacity: 50
        # thread keep alive for 10s
        keepAlive: 10s
        #
        allowCoreThreadTimeout: false
    scheduling:
      pool:
        size: 3

拒絕的策略無法透過參數設定修改，只能使用預設的 AbortPolicy

---

自訂 thread pool bean

TaskConfig.java 產生兩個 thread pool: taskExecutor1, taskExecutor2

package com.test.task;

import org.springframework.boot.autoconfigure.task.TaskExecutionProperties;
import org.springframework.boot.context.properties.PropertyMapper;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Lazy;
import org.springframework.context.annotation.Primary;
import org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor;

import java.time.Duration;
import java.util.concurrent.ThreadPoolExecutor;

@Configuration
public class TaskConfig {

    @Lazy
    @Bean
    @Primary
    public ThreadPoolTaskExecutor taskExecutor1(TaskExecutionProperties taskExecutionProperties) {
        ThreadPoolTaskExecutor taskExecutor = new ThreadPoolTaskExecutor();

        PropertyMapper map = PropertyMapper.get().alwaysApplyingWhenNonNull();
        TaskExecutionProperties.Pool pool = taskExecutionProperties.getPool();
        map.from(pool::getQueueCapacity).to(taskExecutor::setQueueCapacity);
        map.from(pool::getCoreSize).to(taskExecutor::setCorePoolSize);
        map.from(pool::getMaxSize).to(taskExecutor::setMaxPoolSize);
        map.from(pool::getKeepAlive).asInt(Duration::getSeconds).to(taskExecutor::setKeepAliveSeconds);
        map.from(pool::isAllowCoreThreadTimeout).to(taskExecutor::setAllowCoreThreadTimeOut);
        map.from("my-task1-").whenHasText().to(taskExecutor::setThreadNamePrefix);

        // default: AbortPolicy
        taskExecutor.setRejectedExecutionHandler(new ThreadPoolExecutor.AbortPolicy());

        return taskExecutor;
    }

    @Lazy
    @Bean
    public ThreadPoolTaskExecutor taskExecutor2(TaskExecutionProperties taskExecutionProperties) {
        ThreadPoolTaskExecutor taskExecutor = new ThreadPoolTaskExecutor();

        PropertyMapper map = PropertyMapper.get().alwaysApplyingWhenNonNull();
        TaskExecutionProperties.Pool pool = taskExecutionProperties.getPool();
        map.from(10).to(taskExecutor::setQueueCapacity);
        map.from(3).to(taskExecutor::setCorePoolSize);
        map.from(5).to(taskExecutor::setMaxPoolSize);
        map.from(20).to(taskExecutor::setKeepAliveSeconds);
        map.from(true).to(taskExecutor::setAllowCoreThreadTimeOut);
        map.from("my-task2-").whenHasText().to(taskExecutor::setThreadNamePrefix);

        return taskExecutor;
    }
}

修改剛剛的 SimpleTask

@Async("taskExecutor2") 加上 taskExecutor2，指定 thread pool

@Slf4j
@Component
public class SimpleTask {

    @Async("taskExecutor2")
    @Scheduled(cron = "*/3 * * * * *")
    public void printTask() {
        log.info("SimpleTask is working ...");
    }

}

執行結果

[     my-task2-1] com.test.task.SimpleTask                 : SimpleTask is working ...
[     my-task2-2] com.test.task.SimpleTask                 : SimpleTask is working ...
[     my-task2-3] com.test.task.SimpleTask                 : SimpleTask is working ...
[     my-task2-1] com.test.task.SimpleTask                 : SimpleTask is working ...

Spring Boot 3 Data 2

Spring Data JPA

JPA: Java Persistence API，提供 POJO 物件持久化的標準規格，可把 Java 物件直接映射到資料庫中

JPA 是規格，Hibermate, TopLink, OpenJPA 都是 JPA 的實作。目前以 Hibernate 為 Java 最流行的 JPA framework。

Spring Data JPA 底層也是使用 Hibernate，最後透過 JDBC 連接資料庫。

spring-boot-starter-data-jpa 自動設定了 JPA，自動設定類別是

• JpaRepositoriesAutoConfiguration

• HibernateJpaAutoConfiguration

pom.xml

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-jpa</artifactId>
        </dependency>

        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <scope>provided</scope>
        </dependency>

        <dependency>
            <groupId>com.mysql</groupId>
            <artifactId>mysql-connector-j</artifactId>
        </dependency>

        <dependency>
            <groupId>org.hibernate.orm</groupId>
            <artifactId>hibernate-community-dialects</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>

application.yml

spring:
  application:
    name: data2

  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://localhost/testweb
    username: root
    password: password

  jpa:
    hibernate:
      ddl-auto: update
    show-sql: true
    properties:
      hibernate:
        # dialect: org.hibernate.dialect.MySQLDialect
        dialect: org.hibernate.community.dialect.MySQLLegacyDialect

傳統的 JPA 必需要設定 persistence.xml，但在 spring boot 不需要。

Entity class 只需要有 @Entity，@SpringBootApplication 或是 @EnableAutoConfiguration 就會自動掃描所有 @Entity

Data2Application 直接啟動即可

@SpringBootApplication
public class Data2Application {

    public static void main(String[] args) {
        SpringApplication.run(Data2Application.class, args);
    }

}

UserController.java

package com.test.data2.controller;

import com.test.data2.entity.UserDO;
import com.test.data2.repo.UserRepository;
import lombok.RequiredArgsConstructor;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;

@RequiredArgsConstructor
@RestController
public class UserController {

    private final UserRepository userRepository;

    @GetMapping("/user/info/{id}")
    public UserDO getUserInfo(@PathVariable("id") long id){
        UserDO userDO = userRepository.findById(id).orElseGet(null);
        return userDO;
    }

}

UserRepository.java

package com.test.data2.repo;

import com.test.data2.entity.UserDO;
import org.springframework.data.repository.CrudRepository;

public interface UserRepository extends CrudRepository<UserDO, Long> {

}

UserDO.java

package com.test.data2.entity;

import jakarta.persistence.*;
import lombok.Data;

import java.io.Serializable;
import java.util.Date;

@Data
@Entity(name = "user")
public class UserDO implements Serializable {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false, unique = true)
    private String username;

    @Column(nullable = false)
    private String phone;

    @Column(name = "create_time", nullable = false)
    private Date createTime;

    @Column(nullable = false)
    private Integer status;

}

啟動後，可從網址 http://localhost:8080/user/info/2 取得 userid = 2 的資料

console 會出現 sql

Hibernate: select ud1_0.id,ud1_0.create_time,ud1_0.phone,ud1_0.status,ud1_0.username from user ud1_0 where ud1_0.id=?

---

note:

如果掃描不到，可加上 @EntityScan 指定 package/class

Spring data JPA 的 db operation 稱為 repository

• org.springframework.data.repository.CrudRepository

• org.springframework.data.repository.ListCrudRepository

• org.springframework.data.repository.ListPagingRepository

• org.springframework.data.repository.PagingAndSortingRepository

• org.springframework.data.repository.kotlin.*

• org.springframework.data.repository.reactive.*

UserRepository interface 會被自動掃描到，在 controller 能自動注入使用

---

MyBatis

MyBatis是一個Java持久化框架，它通過 XML 或 annotation 把物件與儲存程序或SQL語句關聯起來，對映成資料庫內對應的 record。

MyBatis-Plus 是 MyBatis 的封裝。

---

Redis

REmote DIctionary Server: Redis，是一種 key-value 的 NoSQL memory database。通常用在 cache 資料。

spring-boot-starter-data-redis

org.springframework.boot.autoconfigure.AutoConfiguration.imports 有註冊幾個自動設定類別

• RedisAutoConfiguration

• RedisReactiveAutoConfiguration

• RedisRepositoriesAutoConfiguration

RedisAutoConfiguration 對應的參數綁定類別是 RedisProperties

在 application.yml 設定即可使用

spring:
  application:
    name: data3
  data:
    redis:
      host: localhost
      port: 6379
      database: 0
      password: password
#      client-type: jedis

---

RedisTemplate

有兩個預設的模板可直接使用

• RedisTemplate

  可處理 <Object, Object>

• StringRedisTemplate

  只能處理 <String, String> 的資料，預設使用 JDK 的 serializer

因為 StringRedisTemplate 繼承自 RedisTemplate，必須設定兩個 RedisTemplate，所以要搭配 @ConditionalOnSingleCandidate 注入

RedisTemplate 提供的 interface:

interface	desc
GeoOperations	地理空間
HashOperations	Hash data
HyperLogLogOperations	HyperLogLog
ListOperations	List
SetOperations	Set
ValueOperations	String
ZSetOperations	Ordered Set

設定 pom.xml，要加上 spring-boot-starter-integration, spring-integration-redis

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-redis</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-integration</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.integration</groupId>
            <artifactId>spring-integration-redis</artifactId>
        </dependency>

        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <scope>provided</scope>
        </dependency>

        <dependency>
            <groupId>org.apache.commons</groupId>
            <artifactId>commons-lang3</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

要新增一個連線，注入 StringRedisTemplate 使用

package com.test.data3;

import lombok.RequiredArgsConstructor;
import org.springframework.data.redis.core.StringRedisTemplate;
import org.springframework.data.redis.core.ValueOperations;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RequiredArgsConstructor
@RestController
public class RedisController2 {

    private final StringRedisTemplate stringRedisTemplate;

    @RequestMapping("/redis2/set")
    public String set(@RequestParam("name") String name, @RequestParam("value") String value) {
        ValueOperations<String, String> valueOperations = stringRedisTemplate.opsForValue();
        valueOperations.set(name, value);
        return valueOperations.get(name);
    }

}

呼叫網址 http://localhost:8080/redis2/set?name=test&value=12345 ，就會設定一個 redis key，可使用 redis-cli 檢查

> redis-cli -a password
127.0.0.1:6379> keys *
1) "test"
127.0.0.1:6379> get test
"12345"

---

也可以直接注入對應的 RedisTemplate 使用 valueOperations

@RequiredArgsConstructor
@RestController
public class RedisController3 {

//    private final StringRedisTemplate stringRedisTemplate;

    @Resource(name = "stringRedisTemplate")
    private ValueOperations<String, String> valueOperations;

    @RequestMapping("/redis3/set")
    public String set(@RequestParam("name") String name, @RequestParam("value") String value) {
        valueOperations.set(name, value);
        return valueOperations.get(name);
    }

}

---

自訂 RedisTemplate

@Configuration
public class RedisConfig {

    @Bean
    public RedisTemplate<String, Object> redisTemplate(RedisConnectionFactory factory) {
        RedisTemplate<String, Object> template = new RedisTemplate<>();
        template.setConnectionFactory(factory);

        StringRedisSerializer stringSerializer = new StringRedisSerializer();
        RedisSerializer jacksonSerializer = getJacksonSerializer();

        template.setKeySerializer(stringSerializer);
        template.setValueSerializer(jacksonSerializer);
        template.setHashKeySerializer(stringSerializer);
        template.setHashValueSerializer(jacksonSerializer);
        template.setEnableTransactionSupport(true);
        template.afterPropertiesSet();

        return template;
    }

    private RedisSerializer getJacksonSerializer() {
        ObjectMapper om = new ObjectMapper();
        om.setVisibility(PropertyAccessor.ALL, JsonAutoDetect.Visibility.ANY);
        om.activateDefaultTyping(LaissezFaireSubTypeValidator.instance,
                ObjectMapper.DefaultTyping.NON_FINAL);
        return new GenericJackson2JsonRedisSerializer(om);
    }
}

這裡 key 使用了 StringRedisSerializer, value 使用了 GenericJackson2JsonRedisSerializer

以下是幾個常用的 serializer

serializer	desc
StringRedisSerializer	String/byte[] 轉換器
JdkSerializationRedisSerializer	JDK serializer
OxmSerializer	XML serializer
Jackson2JsonRedisSerializer	JSON serializer, 需要定義 JavaType
GenericJackson2JsonRedisSerializer	JSON serializer, 不需要定義 JavaType

---

MongoDB

springboot 提供兩種 starter

• spring-boot-starter-data-mongodb

• spring-boot-starter-data-mongodb-reactive

首先修改 pom.xml

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-mongodb</artifactId>
        </dependency>

        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <scope>provided</scope>
        </dependency>

        <dependency>
            <groupId>org.apache.commons</groupId>
            <artifactId>commons-lang3</artifactId>
        </dependency>

在 org.springframework.boot.autoconfigure.AutoConfiguration.imports 註冊了幾個自動設定類別

• MongoDataAutoConfiguration

• MongoReactiveDataAutoConfiguration

• MongoRepositoriesAutoConfiguration

• MongoAutoConfiguration

• MongoReactiveAutoConfiguration

設定 application.yml

spring:
  data:
    mongodb:
      uri: mongodb://localhost:27017/test

使用 mongoTemplate

@RequiredArgsConstructor
@RestController
public class MongoController {

    public static final String COLLECTION_NAME = "test";
    private final MongoTemplate mongoTemplate;

    @RequestMapping("/mongo/insert")
    public User insert(@RequestParam("name") String name, @RequestParam("sex") int sex) {
        // add
        User user = new User(RandomUtils.nextInt(), name, sex);
        mongoTemplate.insert(user, COLLECTION_NAME);

        // query
        Query query = new Query(Criteria.where("name").is(name));
        return mongoTemplate.findOne(query, User.class, COLLECTION_NAME);
    }
}

新增 User.java

package com.test.data4;

import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import org.springframework.data.mongodb.core.mapping.Document;

@NoArgsConstructor
@AllArgsConstructor
@Data
@Document(collection = "test")
public class User {
    private long id;
    private String name;
    private int sex;

}

發送網址 http://localhost:8080/mongo/insert?name=test&sex=1

就會 insert 一筆資料到 mongodb collection: test

/* 1 */
{
    "_id" : NumberLong(708252679),
    "name" : "test",
    "sex" : 1,
    "_class" : "com.test.data4.User"
}

---

MongoRepository

新增 UserRepository

package com.test.data4;

import org.springframework.data.mongodb.repository.MongoRepository;

import java.util.List;

public interface UserRepository extends MongoRepository<User, Long> {

    List<User> findByName(String name);

}

修改 MongoController.java

    private final UserRepository userRepository;

    @RequestMapping("/mongo/insert2")
    public User repoInsert(@RequestParam("name") String name, @RequestParam("sex") int sex) {
        // add
        User user = new User(RandomUtils.nextInt(), name, sex);
        userRepository.save(user);

        // query
        return userRepository.findByName(name).get(0);
    }

發送網址 http://localhost:8080/mongo/insert2?name=test2&sex=1

就會新增 test2

---

Elasticsearch

springboot 支援3種客戶端

• Elasticsearch 官方 REST 客戶端

• Elasticsearch 官方 Java API Client

• spring data elasticsearch 提供的 ReactiveElasticsearchClient

pom.xml

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-elasticsearch</artifactId>
        </dependency>

在 org.spingframework.boot.autoconfigure.AutoConfiguration.imports 註冊了

• ElasticsearchDataAutoConfiguration

• ElasticsearchRepositoriesAutoConfiguration

• ReactiveElasticsearchRepositoriesAutoConfiguration

• ElasticsearchClientAutoConfiguration

• ElasticsearchRestClientAutoConfiguration

• ReactiveElasticsearchClientAutoConfiguration

參數綁定 ElasticsearchProperties

參數 spring.elasticsearch.*

application.yml

spring:
  elasticsearch:
    uris: http://localhost:9200
    connection-timeout: 5s
    socket-timeout: 10s
    username: elastic
    password: password

這邊是用關閉 xpack，使用 http 的方式連線

改用 https 可參考

ref: spring-boot-starter-data-elasticsearch es带x-pack后台配置 - 微信公众号-醉鱼Java - 博客园

---

使用 ElasticsearchTemplate

EsController.java

import lombok.RequiredArgsConstructor;
import org.apache.commons.lang3.RandomUtils;
import org.springframework.data.elasticsearch.client.elc.ElasticsearchTemplate;
import org.springframework.data.elasticsearch.core.mapping.IndexCoordinates;
import org.springframework.data.elasticsearch.core.query.Criteria;
import org.springframework.data.elasticsearch.core.query.CriteriaQuery;
import org.springframework.data.elasticsearch.core.query.Query;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RequiredArgsConstructor
@RestController
public class EsController {

    public static final String INDEX_JAVA = "java";
    private final ElasticsearchTemplate elasticsearchTemplate;

    @RequestMapping("/es/insert")
    public User insert(@RequestParam("name") String name, @RequestParam("sex") int sex) throws InterruptedException {
        // add
        User user = new User(RandomUtils.nextInt(), name, sex);
        IndexCoordinates indexCoordinates =  IndexCoordinates.of(INDEX_JAVA);
        User save = elasticsearchTemplate.save(user, indexCoordinates);

        // delay and query
        Thread.sleep(1000l);
        Query query = new CriteriaQuery(Criteria.where("name").is(name));
        return elasticsearchTemplate.searchOne(query, User.class, indexCoordinates).getContent();
    }
}

User.java

@NoArgsConstructor
@AllArgsConstructor
@Data
@Document(indexName = "java")
public class User {
    private long id;
    private String name;
    private int sex;

}

使用 UserRepository

修改 EsController.java

    private final UserRepository userRepository;
    @RequestMapping("/es/repo/insert")
    public User repoInsert(@RequestParam("name") String name, @RequestParam("sex") int sex) {
        // add
        User user = new User(RandomUtils.nextInt(), name, sex);
        userRepository.save(user);

        // query
        return userRepository.findByName(name).get(0);
    }

UserRepository.java

import org.springframework.data.elasticsearch.repository.ElasticsearchRepository;

import java.util.List;

public interface UserRepository extends ElasticsearchRepository<User, Long> {

    List<User> findByName(String name);

}

程式跟 MongoDB 類似