创建一个kotlin的springboot3的项目

前言#

看完你将学会使用kotlin创建一个springboot3的项目,成品项目,star

项目基础#

gradle kotlin 包管理工具
spring web
spring security 安全工具
spring data jpa 数据管理
spring validation 验证数据
postgresql 数据库
jjwt 生成token和校验token
openapi 自动生成请求

项目结构#

我的不一定是最好的,可以参考一下

1
.
2
├── main
3
│   ├── kotlin
4
│   │   └── top
5
│   │       └── inept
6
│   │           └── blog
7
│   │               ├── IneptBlogServerApplication.kt   启动类
8
│   │               ├── base
9
│   │               │   ├── ApiResponse.kt      Api包装类
10
│   │               │   ├── BaseQueryDTO.kt     基础查询DTO
11
│   │               │   ├── PageResponse.kt     Page包装类
12
│   │               │   ├── QueryBuilder.kt     查询构建工具
13
│   │               │   └── ValidationError.kt  validation校验错误格式
14
│   │               ├── config
15
│   │               │   ├── MessageConfig.kt        i18n配置
16
│   │               │   ├── OpenApiI18nConfig.kt    i18n配置
17
│   │               │   └── SecurityConfig.kt       管理spring security配置
18
│   │               ├── constant
19
│   │               │   └── JwtClaimsConstant.kt    tokenClaims字符串
20
│   │               ├── exception
21
│   │               │   ├── JwtInvalidException.kt  定义异常
22
│   │               │   └── NotFoundException.kt    定义异常
23
│   │               ├── extensions  kotlin扩展函数
24
│   │               │   ├── BaseQyeryDTOExtensions.kt
25
│   │               │   ├── MessageExtensions.kt
26
│   │               │   └── PageResponseExtensions.kt
27
│   │               ├── feature 模块
28
│   │               │   ├── article     文章
29
│   │               │   ├── categories  分类
30
│   │               │   ├── comment     评论
31
│   │               │   ├── tag         标签
32
│   │               │   └── user        用户
33
│   │               │       ├── controller
34
│   │               │       │   ├── AdminUserController.kt  管理员控制器
35
│   │               │       │   ├── OpenUserController.kt   公开控制器
36
│   │               │       │   └── UserUserController.kt   用户控制器
37
│   │               │       ├── pojo
38
│   │               │       │   ├── convert
39
│   │               │       │   │   └── UserConvert.kt  转换DTO VO entity
40
│   │               │       │   ├── dto
41
│   │               │       │   │   ├── CreateUserDTO.kt
42
│   │               │       │   │   ├── LoginUserDTO.kt
43
│   │               │       │   │   ├── QueryUserDTO.kt
44
│   │               │       │   │   ├── UpdateUserDTO.kt
45
│   │               │       │   │   └── UpdateUserProfileDTO.kt
46
│   │               │       │   ├── entity
47
│   │               │       │   │   ├── User.kt     spring data jpa 的 entity
48
│   │               │       │   │   └── enums
49
│   │               │       │   │       └── UserRole.kt
50
│   │               │       │   ├── validated   校验相关
51
│   │               │       │   │   ├── ValidateUserNickname.kt
52
│   │               │       │   │   ├── ValidateUserUsername.kt
53
│   │               │       │   │   ├── ValidatedUserEmail.kt
54
│   │               │       │   │   └── ValidatedUserPassword.kt
55
│   │               │       │   └── vo
56
│   │               │       │       ├── LoginUserVO.kt
57
│   │               │       │       ├── UserPublicVO.kt
58
│   │               │       │       └── UserVO.kt
59
│   │               │       ├── repository  仓库
60
│   │               │       │   ├── UserRepository.kt
61
│   │               │       │   └── UserSpecs.kt        查询相关(Specification)
62
│   │               │       └── service     服务
63
│   │               │           ├── UserService.kt
64
│   │               │           └── impl    服务实现
65
│   │               │               └── UserServiceImpl.kt
66
│   │               ├── filter
67
│   │               │   └── JwtAuthFilter.kt            判断请求头的token有效,在SecurityConfig注册
68
│   │               ├── handler
69
│   │               │   └── GlobalExceptionHandler.kt   全局异常拦截器
70
│   │               ├── properties
71
│   │               │   └── JwtProperties.kt            token配置
72
│   │               └── utils
73
│   │                   ├── DateUtil.kt
74
│   │                   ├── JwtUtil.kt
75
│   │                   ├── PasswordUtil.kt
76
│   │                   └── SecurityUtil.kt
77
│   └── resources
78
│       ├── application-dev.yml     开发配置
79
│       ├── application-prod.yml    发布配置
80
│       ├── application.yml         配置
81
│       ├── data.sql
82
│       ├── i18n
83
│       │   ├── messages.properties
84
│       │   ├── messages_en.properties
85
│       │   ├── openapi.properties
86
│       │   ├── openapi_en.properties
87
│       │   ├── validation.properties
88
│       │   └── validation_en.properties
89
│       ├── schema.sql
90
│       ├── static
91
│       └── templates
92
└── test
93
    └── kotlin
94
        └── top
95
            └── inept
96
                └── blog
97
                    └── IneptBlogServerApplicationTests.kt

使用idea开始创建#

alt text

NOTE
添加必要的依赖

alt text

1.管理好配置#

和我一样在resources目录下创建yml格式的配置吧

创建开发配置#

1
top:
2
  inept:
3
    datasource:
4
      ddl-auto: update
5
      host: 127.0.0.1
6
      port: 5432
7
      database: inept_blog
8
      username: user
9
      password: 123456
10
    server:
11
      port: 8080
12
    jwt:
13
      secretKey: 82MjWAO+36AA+XMmx6dCuLZd8Kaa2sL+KxzDVY5Mvm+xXo5ZcUQe5uZpnv+lhhdgTMjgJpfevyxok0NlXCwb8A==
14
      ttlHours: 168
15
      tokenName: token
16

17
logging:
18
  level:
19
    org:
20
      springframework:
21
        web:
22
          servlet:
23
            DispatcherServlet: DEBUG
24
        validation: DEBUG
25
      hibernate:
26
        validator: DEBUG

创建发布配置#

1
top:
2
  inept:
3
    datasource:
4
      ddl-auto: validate
5
      host: 127.0.0.1
6
      port: 5432
7
      database: inept_blog
8
      username: user
9
      password: 123456
10
    server:
11
      port: 8080
12
    jwt:
13
      secretKey: U7lIBboDJW24Ak1ROncsOyuVNuugnZriJWZBY9ULB//4EdZU5AeGCRlVAdXMKxinBynktrcuQgGVCM4Fm54tBg==  #openssl rand -base64 64
14
      ttlHours: 168  #7day
15
      tokenName: token

创建主配置#

1
spring:
2
  application:
3
    name: inept-test
4
  profiles:
5
    active: dev
6
  datasource:
7
    url: jdbc:postgresql://${top.inept.datasource.host}:${top.inept.datasource.port}/${top.inept.datasource.database}
8
    username: ${top.inept.datasource.username}
9
    password: ${top.inept.datasource.password}
10

11
  jpa:
12
    hibernate:
13
      ddl-auto: ${top.inept.datasource.ddl-auto}
14
    show-sql: true
15
    properties:
16
      hibernate:
17
        format_sql: true
18
    database-platform: org.hibernate.dialect.PostgreSQLDialect
19
    database: postgresql
20

21
  messages:
22
    basename: i18n/messages,i18n/validation,i18n/openapi
23
    encoding: UTF-8
24
    fallback-to-system-locale: false
25

26
server:
27
  port: ${top.inept.server.port}
28

29
top:
30
  inept:
31
    jwt:
32
      secretKey: ${top.inept.jwt.secretKey}
33
      ttlHours: ${top.inept.jwt.ttlHours}
34
      tokenName: ${top.inept.jwt.tokenName}

详细讲解配置#

我们只需要修改开发配置和发布配置

CAUTION
不过再次之前我们需要把application-dev.yml添加到.gitignore中，只需要在行末添加

1
top:
2
  inept:
3
    datasource:
4
      ddl-auto: update
5
      host: 127.0.0.1       #数据库ip或者域名
6
      port: 5432            #数据库端口
7
      database: inept_blog  #数据库名称
8
      username: user        #数据库账号
9
      password: 123456      #数据库密码
10
    server:
11
      port: 8080            #springboot web 开放端口
12
    jwt:
13
      secretKey: 82MjWAO+36AA+XMmx6dCuLZd8Kaa2sL+KxzDVY5Mvm+xXo5ZcUQe5uZpnv+lhhdgTMjgJpfevyxok0NlXCwb8A==   #jwt的secretKey使用openssl rand -base64 64随机生成
14
      ttlHours: 168     #过期时间
15
      tokenName: token
16

17
logging:
18
  level:
19
    org:
20
      springframework:
21
        web:
22
          servlet:
23
            DispatcherServlet: DEBUG
24
        validation: DEBUG
25
      hibernate:
26
        validator: DEBUG

2.添加i18n相关#

在项目结构中可以看到在resources下有个i18n文件夹里面就是关于i18n内容，按照下面创建多个i18n文件

1
├── messages.properties
2
├── messages_en.properties
3
├── openapi.properties
4
├── openapi_en.properties
5
├── validation.properties
6
└── validation_en.properties

默认配置是中文的，大概内容为

1
openapi.query.page=页数
2
openapi.query.size=大小
3

4
openapi.response.code=失败成功数字
5
....

我来说明messages openapi validation这些文件有什么用

`messages`#

通常在服务层使用较为通用，例如message.user.username_or_password_error=用户名或者密码错误

`openapi`#

专为为openapi使用，通常在DTO VO类使用

1
data class UserVO(
2
    @Schema(description = "openapi.user.id")
3
    val id: Long,
4

5
    @Schema(description = "openapi.user.nickname")      //openapi.user.nickname=昵称
6
    val nickname: String,
7

8
    @Schema(description = "openapi.user.username")      //openapi.user.username=用户名
9
    val username: String,
10

11
    @Schema(description = "openapi.user.email")
12
    val email: String?,
13
)

`validation`#

和名字一样在validation使用，例如校验用户提示的错误

1
@Size(min = 2, max = 16, message = "valid.user.nickname")
2
annotation class ValidateUserNickname(
3
    val message: String = "valid.common.unknown_error",
4
    val groups: Array<KClass<*>> = [],
5
    val payload: Array<KClass<out Payload>> = []
6
)

1
valid.user.nickname=错误的昵称格式,长度应为2-16
2
valid.user.username=错误的用户名格式,长度应为6-16
3
valid.user.password=至少一个字母,至少一个数字,长度应为6-20
4
valid.user.email=邮箱校验错误
5
....

3.创建最基础的#

你可以直接在我的成品项目中复制代码，在开头有提到

1.创建`JwtProperties`#

创建这个发布我们在业务代码方便获取到在配置文件写的内容，JwtProperties获取的是关于Jwt的

1
@ConfigurationProperties(prefix = "top.inept.jwt")
2
data class JwtProperties @ConstructorBinding constructor(
3
    val secretKey: String,
4
    val ttlHours: Long,
5
    val tokenName: String,
6
)

2.创建配置类#

1.MessageConfig#

用于解析i18n内容的

1
@Configuration
2
class MessageConfig : WebMvcConfigurer {
3
    @Bean
4
    fun messageAccessor(messageSource: MessageSource): MessageSourceAccessor {
5
        // 这个 accessor 会自动从 LocaleContextHolder 取 locale
6
        return MessageSourceAccessor(messageSource)
7
    }
8
}

创建配套的拓展函数

1
// 单参数，无 args
2
operator fun MessageSourceAccessor.get(code: String): String =
3
    try {
4
        this.getMessage(code)
5
    } catch (ex: NoSuchMessageException) {
6
        code
7
    }
8

9
// 多参数，可传 args
10
operator fun MessageSourceAccessor.get(code: String, vararg args: Any): String =
11
    try {
12
        this.getMessage(code, args)
13
    } catch (ex: NoSuchMessageException) {
14
        code
15
    }

2.OpenApiI18nConfig#

由于openapi不会自动解析我们的i18n内容我需要自己手动解析

1
@Configuration
2
class OpenApiI18nConfig(private val messages: MessageSourceAccessor) {
3
    @Bean
4
    fun i18nCustomizer(): OpenApiCustomizer {
5
        return OpenApiCustomizer { openApi: OpenAPI ->
6
            openApi.components?.schemas?.forEach { (_, schema) ->
7
                translateSchema(schema, messages)
8
            }
9
        }
10
    }
11

12
    private fun translateSchema(schema: Schema<*>, source: MessageSourceAccessor) {
13
        schema.description?.takeIf { it.startsWith("openapi.") }?.also {
14
            schema.description = source[it]
15
        }
16
        schema.properties?.values?.forEach { prop ->
17
            prop?.let { p ->
18
                p.description?.takeIf { it.startsWith("openapi.") }?.also {
19
                    p.description = source[it]
20
                }
21
            }
22
        }
23
    }
24
}

3.一些基础的东西#

ApiResponse#

一个Api包装类,并且之类已经用到openapi的i18n注解了

1
data class ApiResponse<T>(
2
    @Schema(description = "openapi.response.code")
3
    val code: Int = 0,
4

5
    @Schema(description = "openapi.response.msg")   //openapi.response.msg=消息
6
    val msg: String? = null,
7

8
    @Schema(description = "openapi.response.data")
9
    val data: T? = null
10
) : Serializable {
11

12
    companion object {
13
        const val SUCCESS = 0
14
        const val FAILURE = 1
15

16
        /**
17
         * 只返回成功，不带数据
18
         */
19
        fun <T> success(data: T): ApiResponse<T> = ApiResponse(code = SUCCESS, data = data, msg = "success")
20

21
        /**
22
         * 只返回错误信息
23
         */
24
        fun <T> error(msg: String): ApiResponse<T> = ApiResponse(code = FAILURE, msg = msg)
25

26
        fun <T> error(msg: String, data: T): ApiResponse<T> = ApiResponse(code = FAILURE, msg = msg, data = data)
27
    }
28
}

ValidationError#

自定义validation返回的错误消息格式，在下面的全局拦截器有提到

1
data class ValidationError(val field: String, val message: String)

4.创建全局的异常拦截器#

1
@RestControllerAdvice
2
class GlobalExceptionHandler(
3
    private val messages: MessageSourceAccessor
4
) {
5
    private val logger = LoggerFactory.getLogger(this::class.java)
6

7
    @ExceptionHandler
8
    fun exceptionHandler(ex: Exception): ApiResponse<String> {
9
        logger.error(ex.message, ex)
10

11
        return ApiResponse.error(ex.message ?: messages["message.common.unknown_error"])    //message.common.unknown_error=未知错误
12
    }
13

14
    @ExceptionHandler
15
    fun exceptionHandler(ex: HttpMessageNotReadableException): ApiResponse<String> {
16
        logger.error(ex.message, ex)
17

18
        //json解析时缺少字段报错
19
        if (ex.cause is MissingKotlinParameterException) {
20
            return ApiResponse.error(messages["message.common.missing_json_field", ex.message ?: "Null"])
21
        }
22

23
        return ApiResponse.error(ex.message ?: messages["message.common.unknown_error"])
24
    }
25

26
    /**
27
     * Validated的验证错误
28
     */
29
    @ExceptionHandler(MethodArgumentNotValidException::class)
30
    fun exceptionHandler(ex: MethodArgumentNotValidException): ApiResponse<List<ValidationError>> {
31
        val errors = ex.bindingResult.fieldErrors.map { fe ->
32
            ValidationError(
33
                field = fe.field,
34
                message = messages[fe.defaultMessage ?: "message.common.illegal_parameters"],
35
            )
36
        }
37

38
        return ApiResponse.error(messages["message.common.illegal_parameters"], errors)
39
    }
40
}

4.在启动类中添加需要的注释#

下面这个是默认的启动类，可能你创建项目名字不同和我的不太一样

1
@SpringBootApplication
2
@EnableJpaAuditing                                          //JPA 中启用审计
3
@EnableConfigurationProperties(JwtProperties::class)        //给刚刚创建的JwtProperties添加上
4
class IneptBlogServerApplication
5

6
fun main(args: Array<String>) {
7
    runApplication<IneptBlogServerApplication>(*args)
8
}

5.配置认证过滤器#

1.创建JwtUtil#

由于我这里的JwtUtil没有和UserRole解耦，你们最好看一下成品项目

1
package top.inept.blog.utils
2

3
import io.jsonwebtoken.*
4
import org.springframework.context.support.MessageSourceAccessor
5
import org.springframework.stereotype.Component
6
import top.inept.blog.constant.JwtClaimsConstant
7
import top.inept.blog.exception.JwtInvalidException
8
import top.inept.blog.extensions.get
9
import top.inept.blog.feature.user.pojo.entity.enums.UserRole
10
import java.util.*
11
import javax.crypto.spec.SecretKeySpec
12

13
@Component
14
class JwtUtil(private val messages: MessageSourceAccessor) {
15
    private fun createJWT(
16
        secretKey: String,
17
        ttlHours: Long,
18
        claims: Map<String, Any>
19
    ): String {
20
        val now = Date(System.currentTimeMillis())
21
        val hmacKey = SecretKeySpec(Base64.getDecoder().decode(secretKey), "HmacSHA512")
22

23
        return Jwts.builder()
24
            .claims(claims)
25
            .issuedAt(now)
26
            .expiration(DateUtil.addHoursToDate(now, ttlHours))
27
            .signWith(hmacKey)
28
            .compact()
29
    }
30

31
    fun createJWT(
32
        secretKey: String,
33
        ttlHours: Long,
34
        id: Long,
35
        username: String,
36
        role: UserRole,
37
    ): String {
38
        val payload = HashMap<String, Any>()
39
        payload.put(JwtClaimsConstant.ID, id)
40
        payload.put(JwtClaimsConstant.USERNAME, username)
41
        payload.put(JwtClaimsConstant.ROLE, role.toString())
42

43
        return createJWT(secretKey, ttlHours, payload)
44
    }
45

46
    fun parseJWT(
47
        secretKey: String,
48
        token: String
49
    ): Jws<Claims> {
50
        val hmacKey = SecretKeySpec(Base64.getDecoder().decode(secretKey), "HmacSHA512")
51

52
        return try {
53
            Jwts.parser()
54
                .verifyWith(hmacKey)
55
                .build()
56
                .parseSignedClaims(token)
57
        } catch (e: ExpiredJwtException) {
58
            throw JwtInvalidException(messages["message.jwt.expired"])
59
        } catch (e: JwtException) {
60
            throw JwtInvalidException(messages["message.jwt.invalid"])
61
        }
62
    }
63

64
    fun getIdFromClaims(claims: Claims): Long? {
65
        val raw = claims[JwtClaimsConstant.ID]
66

67
        return when (raw) {
68
            is Number -> raw.toLong()
69
            is String -> raw.toLongOrNull()
70
            else -> null
71
        }
72
    }
73

74
    fun getUsernameFromClaims(claims: Claims): String? {
75
        val raw = claims[JwtClaimsConstant.USERNAME]
76
        return raw as? String
77
    }
78

79
    fun getRoleFromClaims(claims: Claims): UserRole? {
80
        val raw = claims[JwtClaimsConstant.ROLE]
81
        if (raw !is String) return null
82

83
        return try {
84
            UserRole.valueOf(raw)
85
        } catch (e: IllegalArgumentException) {
86
            null
87
        }
88
    }
89
}

1
class JwtInvalidException(message: String) : RuntimeException(message)

1
object DateUtil {
2
    fun addHoursToDate(date: Date, hours: Long): Date {
3
        val instant = date.toInstant()
4
        val newInstant = instant.plus(Duration.ofHours(hours))
5
        return Date.from(newInstant)
6
    }
7
}

2.创建JwtAuthFilter#

1
@Component
2
    class JwtAuthFilter(
3
    private val jwtProperties: JwtProperties,
4
    private val jwtUtil: JwtUtil,
5
) : OncePerRequestFilter() {
6

7
    override fun doFilterInternal(
8
        request: HttpServletRequest,
9
        response: HttpServletResponse,
10
        filterChain: FilterChain
11
    ) {
12
        //判断有没有token
13
        val authHeader = request.getHeader("Authorization")
14
        if (authHeader == null || !authHeader.startsWith("Bearer ")) {
15
            filterChain.doFilter(request, response)
16
            return
17
        }
18

19
        //获取token
20
        val token = authHeader.substring(7)
21

22
        //解析token
23
        val claims = jwtUtil.parseJWT(secretKey = jwtProperties.secretKey, token)
24

25
        //获取用户名与role
26
        val username = jwtUtil.getUsernameFromClaims(claims.payload)
27
        val role = jwtUtil.getRoleFromClaims(claims.payload)
28

29
        if (username == null || role == null) {
30
            filterChain.doFilter(request, response)
31
            return
32
        }
33

34
        // 如果上下文中没有认证信息，才进行设置
35
        if (SecurityContextHolder.getContext().authentication == null) {
36

37
            val authToken = UsernamePasswordAuthenticationToken(
38
                username,
39
                null,
40
                listOf<GrantedAuthority>(role)
41
            )
42
            authToken.details = WebAuthenticationDetailsSource().buildDetails(request)
43

44
            // 将认证对象设置到 SecurityContext 中，表示当前用户已认证
45
            SecurityContextHolder.getContext().authentication = authToken
46
        }
47

48
        filterChain.doFilter(request, response)
49
    }
50
}

3.创建SecurityConfig配置类#

1
@Configuration
2
@EnableWebSecurity
3
class SecurityConfig(
4
    private val jwtAuthFilter: JwtAuthFilter,
5
) {
6
    @Bean
7
    fun securityFilterChain(http: HttpSecurity): SecurityFilterChain {
8
        http.invoke {
9
            // 禁用 CSRF，因为我们使用无状态的 JWT
10
            csrf { disable() }
11

12
            authorizeHttpRequests {
13
                // 定义访问权限
14
                authorize("/open/**", permitAll)
15
                authorize("/user/**", hasAuthority(UserRole.USER.authority)) // /user/** 路径需要 USER 角色
16
                authorize("/admin/**", hasAuthority(UserRole.ADMIN.authority)) // /admin/** 路径需要 ADMIN 角色
17

18
                //TODO 发布时关闭
19
                authorize("/swagger-ui/**", permitAll)
20
                authorize("/v3/api-docs/**", permitAll)
21

22
                authorize(anyRequest, authenticated) // 其他所有请求都需要认证
23
            }
24

25
            // 设置 Session 管理策略为 STATELESS (无状态)
26
            sessionManagement {
27
                sessionCreationPolicy = SessionCreationPolicy.STATELESS
28
            }
29

30
            addFilterBefore(jwtAuthFilter, UsernamePasswordAuthenticationFilter::class.java)
31
        }
32
        return http.build()
33
    }
34
}

前言#

项目基础#

项目结构#

使用idea开始创建#

1.管理好配置#

创建开发配置#

创建发布配置#

创建主配置#

详细讲解配置#

2.添加i18n相关#

messages#

openapi#

validation#

3.创建最基础的#

1.创建JwtProperties#

2.创建配置类#

1.MessageConfig#

2.OpenApiI18nConfig#

3.一些基础的东西#

ApiResponse#

ValidationError#

4.创建全局的异常拦截器#

4.在启动类中添加需要的注释#

5.配置认证过滤器#

1.创建JwtUtil#

2.创建JwtAuthFilter#

3.创建SecurityConfig配置类#

`messages`#

`openapi`#

`validation`#

1.创建`JwtProperties`#