Quick Start - lifedever/kt-speedy-toolbox GitHub Wiki

快速开始指南

本指南将帮助你在5分钟内快速上手 KT Speedy Toolbox。

📋 目录

环境准备

系统要求

  • JDK: 8 或更高版本
  • Kotlin: 1.9.23 或更高版本
  • 构建工具: Maven 3.6+ 或 Gradle 6.0+

验证环境

# 检查 Java 版本
java -version

# 检查 Kotlin 版本（如果已安装）
kotlin -version

添加依赖

Maven 项目

在 pom.xml 中添加依赖：

<dependencies>
    <!-- 核心工具模块 -->
    <dependency>
        <groupId>kt.speedy.toolbox</groupId>
        <artifactId>kt-speedy-util</artifactId>
        <version>1.1.40</version>
    </dependency>
    
    <!-- JPA 模块（可选，如果使用 Spring Data JPA） -->
    <dependency>
        <groupId>kt.speedy.toolbox</groupId>
        <artifactId>kt-speedy-data-jpa</artifactId>
        <version>1.1.40</version>
    </dependency>
    
    <!-- MongoDB 模块（可选，如果使用 Spring Data MongoDB） -->
    <dependency>
        <groupId>kt.speedy.toolbox</groupId>
        <artifactId>kt-speedy-data-mongo</artifactId>
        <version>1.1.40</version>
    </dependency>
</dependencies>

Gradle 项目

在 build.gradle.kts 中添加依赖：

dependencies {
    // 核心工具模块
    implementation("kt.speedy.toolbox:kt-speedy-util:1.1.40")
    
    // JPA 模块（可选）
    implementation("kt.speedy.toolbox:kt-speedy-data-jpa:1.1.40")
    
    // MongoDB 模块（可选）
    implementation("kt.speedy.toolbox:kt-speedy-data-mongo:1.1.40")
}

基础使用

1. 字符串处理

import kt.speedy.toolbox.util.*

fun main() {
    // 字符串验证
    val email = "[email protected]"
    if (email.isPresent()) {
        println("邮箱有效: $email")
    }
    
    // 字符串加密
    val password = "myPassword123"
    val hashedPassword = password.md5()
    println("MD5: $hashedPassword")
    
    // 路径拼接
    val apiBase = "/api/v1"
    val endpoint = "users"
    val fullPath = apiBase.pathAppend(endpoint)
    println("完整路径: $fullPath") // /api/v1/users
    
    // 模糊查询
    val searchTerm = "kotlin"
    val likeQuery = searchTerm.toLikeQuery()
    println("LIKE 查询: $likeQuery") // %kotlin%
}

2. 数值计算

import kt.speedy.toolbox.util.*

fun main() {
    // 安全除法
    val a = 100.0
    val b = 3.0
    val result = a.ddiv(b, 2) // 保留2位小数
    println("除法结果: $result") // 33.33
    
    // 百分比转换
    val rate = 0.856
    println("百分比: ${rate.toPercentStr()}") // 85.6%
    
    // 精确计算
    val price = 99.99
    val discount = 0.15
    val finalPrice = price.mmul(1.0.ssub(discount))
    println("折后价格: ${finalPrice.round(2)}") // 84.99
}

3. 日期时间操作

import kt.speedy.toolbox.util.*
import org.joda.time.DateTime
import java.util.*

fun main() {
    // 当前时间操作
    val now = DateTime.now()
    println("今天开始: ${now.startOfDay()}")
    println("今天结束: ${now.endOfDay()}")
    println("本月开始: ${now.startOfMonth()}")
    
    // 日期格式化
    val date = Date()
    println("格式化日期: ${date.format("yyyy-MM-dd HH:mm:ss")}")
    
    // 字符串转日期
    val dateStr = "2024-01-15"
    val parsedDate = dateStr.toDate()
    println("解析日期: $parsedDate")
}

4. 集合操作

import kt.speedy.toolbox.util.*

fun main() {
    // 集合验证
    val list = listOf(1, 2, 3, 4, 5)
    if (list.isPresent()) {
        println("列表不为空，包含 ${list.size} 个元素")
    }
    
    // 条件执行
    val emptyList = emptyList<String>()
    emptyList.ifNotPresent {
        println("列表为空，执行默认操作")
    }
}

JPA 模块使用

1. 创建实体类

import kt.speedy.toolbox.data.jpa.SupportModal
import jakarta.persistence.*

@Entity
@Table(name = "users")
class User : SupportModal() {
    @Column(name = "username", nullable = false, unique = true)
    var username: String? = null
    
    @Column(name = "email", nullable = false)
    var email: String? = null
    
    @Column(name = "phone")
    var phone: String? = null
}

2. 创建仓库接口

import kt.speedy.toolbox.data.jpa.SupportRepository
import org.springframework.stereotype.Repository

@Repository
interface UserRepository : SupportRepository<User, String> {
    fun findByUsername(username: String): User?
    fun findByEmailContaining(email: String): List<User>
}

3. 创建服务类

import kt.speedy.toolbox.data.jpa.SupportService
import kt.speedy.toolbox.data.jpa.SpecificationBuilder
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.data.domain.Page
import org.springframework.data.domain.PageRequest
import org.springframework.data.domain.Sort
import org.springframework.data.jpa.domain.Specification
import org.springframework.stereotype.Service

@Service
class UserService : SupportService<User, String>() {
    
    @Autowired
    override lateinit var repository: UserRepository
    
    fun createUser(username: String, email: String): User {
        val user = User().apply {
            this.username = username
            this.email = email
        }
        return save(user)
    }
    
    fun searchUsers(keyword: String?, page: Int, size: Int): Page<User> {
        val spec = SpecificationBuilder.builder<User>()
            .apply {
                keyword?.let {
                    and(Specification.where { root, _, cb ->
                        cb.or(
                            cb.like(root.get("username"), "%$it%"),
                            cb.like(root.get("email"), "%$it%")
                        )
                    })
                }
            }
            .build()
        
        val pageable = PageRequest.of(page, size, Sort.by("createdDate").descending())
        return findAll(spec, pageable)
    }
}

4. 配置审计功能

import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.data.domain.AuditorAware
import org.springframework.data.jpa.config.EnableJpaAuditing
import java.util.*

@Configuration
@EnableJpaAuditing
class JpaConfig {
    
    @Bean
    fun auditorProvider(): AuditorAware<String> {
        return AuditorAware {
            // 这里可以从 Security Context 获取当前用户
            Optional.of("system")
        }
    }
}

MongoDB 模块使用

1. 创建文档类

import kt.speedy.toolbox.data.mongo.MongoSupportModel
import org.springframework.data.mongodb.core.mapping.Document

@Document(collection = "articles")
class Article : MongoSupportModel() {
    var title: String? = null
    var content: String? = null
    var author: String? = null
    var tags: List<String> = emptyList()
    var published: Boolean = false
}

2. 创建服务类

import kt.speedy.toolbox.data.mongo.MongoSupportService
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.data.domain.Page
import org.springframework.data.domain.PageRequest
import org.springframework.data.domain.Sort
import org.springframework.data.mongodb.core.MongoTemplate
import org.springframework.data.mongodb.core.query.Criteria
import org.springframework.data.mongodb.core.query.Query
import org.springframework.stereotype.Service

@Service
class ArticleService : MongoSupportService<Article>(Article::class.java) {
    
    @Autowired
    override lateinit var template: MongoTemplate
    
    fun createArticle(title: String, content: String, author: String): Article {
        val article = Article().apply {
            this.title = title
            this.content = content
            this.author = author
        }
        return save(article)
    }
    
    fun findPublishedArticles(page: Int, size: Int): Page<Article> {
        val query = Query()
            .addCriteria(Criteria.where("published").`is`(true))
            .addCriteria(Criteria.where("deleted").`is`(false))
        
        val pageable = PageRequest.of(page, size, Sort.by("createdDate").descending())
        return findByQuery(query, pageable)
    }
    
    fun searchArticles(keyword: String): List<Article> {
        val regex = ".*$keyword.*"
        val query = Query()
            .addCriteria(
                Criteria().orOperator(
                    Criteria.where("title").regex(regex, "i"),
                    Criteria.where("content").regex(regex, "i")
                )
            )
            .addCriteria(Criteria.where("deleted").`is`(false))
        
        return findByQuery(query)
    }
}

常见问题

Q: 如何只使用部分功能？

A: 你可以只添加需要的模块依赖。如果只需要工具函数，只添加 kt-speedy-util 即可。

Q: 与 Spring Boot 的兼容性如何？

A: 完全兼容 Spring Boot 3.x，JPA 和 MongoDB 模块都基于 Spring Boot 3.3.2 开发。

Q: 如何自定义 ID 生成策略？

A: 可以重写实体类的 init 方法或者在保存前手动设置 ID。

Q: 日期时间扩展依赖什么库？

A: 主要依赖 Joda-Time 库，提供了丰富的日期时间操作功能。

Q: 如何处理时区问题？

A: 使用 toDateTimeUTC() 方法可以转换为 UTC 时区，或者使用 toDateTime(zone) 指定时区。

下一步

现在你已经掌握了基础用法，可以：

  1. 查看 API 文档 了解更多功能
  2. 阅读 最佳实践 学习推荐用法
  3. 查看具体模块的详细文档：

🤝 获取帮助

如果遇到问题：

  1. 查看 常见问题
  2. 搜索 GitHub Issues
  3. 提交新的 Issue
⚠️ **GitHub.com Fallback** ⚠️