用于（反）序列化 REST API 的请求和响应的模型的命名约定

Question

我需要在 REST API 客户端中创建一些类来处理数据的（反）序列化，并且我不使用如何以有意义的方式命名这些类。

例如，使用以下 API

GET  /User
POST /Message

我想到使用这个结构：

package com.example.model

import kotlinx.serialization.Serializable

object User {
    @Serializable
    data class Response(
        val username: String,
        val fullName: String
    )
}

object Message {
    @Serializable
    data class Request(
        val title: String,
        val message: String
    )
    @Serializable
    data class Response(
        val status: Int
    )
}

但我不知道如何处理这样的事情（假设所有请求和响应都有不同的结构）：

GET    /User
POST   /Message
DELETE /Message

我想到了这样的事情：

object UserGet { ... }
object MessagePost { ... }
object MessageDelete { ... }

但后来我不知道如何处理这个问题：

GET    /User
GET    /User/{userId}
GET    /User/{userId}/AllMessages
POST   /Message
DELETE /Message

这个用例有约定吗？服务器端通常如何处理？

Answer 1

您可以保留类名称，只需向其中添加与支持的请求方法相对应的方法即可。

package com.example.model

import kotlinx.serialization.Serializable

object User {
    @Serializable
    data class Request( // either you or your routing library should parse incoming urls to deserialize this
        val user_id: String
    )
    @Serializable
    data class Response(
        val username: String,
        val fullName: String
    )
    fun get(req: Request): Response {
    } // GET /User/{user_id}
}

object Message {
    @Serializable
    data class Request(
        val title: String,
        val message: String
    )
    @Serializable
    data class Response(
        val status: Int
    )
    fun create(req: Request): Response {
    } // POST /Message
    fun delete(req: Request): Response {
    } // DELETE /Message
}

GET /user- 您需要为此定义行为。目前我看不出这会在您的系统中起什么作用。

GET /user/{user_id}/AllMessages- 这有效地映射到一组不同的资源。一个新的班级可能是有序的。我还推荐一个更规范的名称，例如GET /user/{user_id}/messages. 这样，您可以使用查询字符串提供分页参数?limit=1000&offset=900

object UserMessages {
    @Serializable
    data class Request(
        val user_id: String,
        val limit: Int,
        val offset: Int
    )
    @Serializable
    data class Message(
        val message_id: String,
        val text: String
    )
    @Serializable
    data class Response(
        val messages: Array<Message>
    )
    fun get(req: Request): Response {
    } // GET /user/{user_id}/messages
}