GraphQL API 与 Kotlin：逐步实践教程

引言：为什么 GraphQL 和 Kotlin 是完美搭档？

在现代 Web 开发中，选择合适的 API 创建工具直接决定了开发速度和维护便捷性。GraphQL 是一种查询语言，允许客户端只请求所需的数据，消除了 REST 固有的过度获取和获取不足问题。Kotlin 则是一种现代、简洁且安全的语言，特别适合与 Spring Boot 结合进行后端开发。

在本教程中，我们将用 Kotlin 实际构建一个完整的 GraphQL API。你将学习如何设置服务器、定义模式、实现查询和变更，以及测试最终的 API。文章结束时，你将拥有一个可运行的项目，并可以作为自己应用的基础。

1. 项目设置与依赖

首先，我们创建一个支持 GraphQL 的新 Spring Boot 项目。我们将使用 Spring for GraphQL —— 这是官方的集成方案，能让工作尽可能简单。

1.1. 创建项目

你可以使用 Spring Initializr 或任何 IDE（如 IntelliJ IDEA）。添加以下依赖：

• Spring Web
• Spring for GraphQL
• Spring Data JPA
• H2 数据库（为简化起见）

build.gradle.kts 文件应包含以下内容：

dependencies {    implementation("org.springframework.boot:spring-boot-starter-web")    implementation("org.springframework.boot:spring-boot-starter-graphql")    implementation("org.springframework.boot:spring-boot-starter-data-jpa")    runtimeOnly("com.h2database:h2")    testImplementation("org.springframework.boot:spring-boot-starter-test")}

1.2. 配置

我们创建一个简单的 Book 实体和一个用于操作数据库的仓库。

// Book.kt@Entitydata class Book(    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)    val id: Long = 0,    val title: String,    val author: String,    val year: Int)

// BookRepository.ktinterface BookRepository : JpaRepository<Book, Long>

2. 创建 GraphQL 模式与控制器

GraphQL 使用严格的类型系统。模式定义了哪些数据可用以及如何查询这些数据。在 Spring for GraphQL 中，可以使用注解来描述模式。

2.1. 通过代码定义模式

我们创建一个控制器类来处理 GraphQL 查询。使用 @QueryMapping 注解读取数据，使用 @MutationMapping 注解进行修改。

// BookController.kt@Controllerclass BookController(private val repository: BookRepository) {

    @QueryMapping    fun allBooks(): List<Book> = repository.findAll()

    @QueryMapping    fun bookById(@Argument id: Long): Book? = repository.findById(id).orElse(null)

    @MutationMapping    fun addBook(@Argument title: String, @Argument author: String, @Argument year: Int): Book {        val book = Book(title = title, author = author, year = year)        return repository.save(book)    }

    @MutationMapping    fun deleteBook(@Argument id: Long): Boolean {        if (repository.existsById(id)) {            repository.deleteById(id)            return true        }        return false    }}

2.2. 替代方案：.graphqls 模式文件

你也可以在 resources/graphql 文件夹中创建一个单独的 schema.graphqls 文件来定义模式：

type Query {    allBooks: [Book]    bookById(id: ID!): Book}

type Mutation {    addBook(title: String!, author: String!, year: Int!): Book    deleteBook(id: ID!): Boolean}

type Book {    id: ID!    title: S