如何在基于Spring的强types语言中正确地使用PATCH – example

据我所知:

  • PUT – 用其整个表示更新对象(replace)
  • 修补程序 – 仅使用给定字段更新对象(更新)

我正在使用Spring来实现一个非常简单的HTTP服务器。 当用户想要更新他的数据时,他需要为某个端点(比如: api/user )创build一个HTTP PATCH 。 他的请求体通过@RequestBody映射到DTO,如下所示:

 class PatchUserRequest { @Email @Length(min = 5, max = 50) var email: String? = null @Length(max = 100) var name: String? = null ... } 

然后我使用这个类的一个对象来更新(修补)用户对象:

 fun patchWithRequest(userRequest: PatchUserRequest) { if (!userRequest.email.isNullOrEmpty()) { email = userRequest.email!! } if (!userRequest.name.isNullOrEmpty()) { name = userRequest.name } ... } 

我的疑问是:如果一个客户端(例如Web应用程序)想要清除一个属性,该怎么办? 我会忽略这样的改变。

我怎么知道,如果一个用户想清除一个属性(他故意给我发空),或者他只是不想改变它? 在这两种情况下,我的对象都是空的。

我可以在这里看到两个选项:

  • 同意客户,如果他想要删除一个属性,他应该给我一个空string(但是date和其他非stringtypes呢?)
  • 停止使用DTO映射,并使用一个简单的地图,这将让我检查是否一个字段被赋予空或根本不给。 那么请求身体validation呢? 我现在使用@Valid

应如何妥善处理这种情况,与REST和所有良好做法协调一致?

编辑:

可以说, PATCH不应该用在这样的例子中,我应该使用PUT来更新我的用户。 但是,那么API更新(例如添加一个新的属性)呢? 我将不得不版本我的API(或版本用户端点); 在每次用户更改之后, api/v1/user ,接受PUT与一个旧的请求主体, api/v2/user接受PUT与一个新的请求主体,等等。我想这不是解决scheme和PATCH存在的原因。

TL; DR

patchy是一个小型库,我已经拿出了照顾在春季正确处理PATCH所需的主要样板代码,即:

 class Request : PatchyRequest { @get:NotBlank val name:String? by { _changes } override var _changes = mapOf<String,Any?>() } @RestController class PatchingCtrl { @RequestMapping("/", method = arrayOf(RequestMethod.PATCH)) fun update(@Valid request: Request){ request.applyChangesTo(entity) } } 

解决scheme简单

由于PATCH请求表示要应用于资源的更改,因此我们需要明确地对其进行build模。

一种方法是使用普通的旧的Map<String,Any?> ,其中客户端提交的每个key都代表对资源相应属性的更改:

 @RequestMapping("/entity/{id}", method = arrayOf(RequestMethod.PATCH)) fun update(@RequestBody changes:Map<String,Any?>, @PathVariable id:Long) { val entity = db.find<Entity>(id) changes.forEach { entry -> when(entry.key){ "firstName" -> entity.firstName = entry.value?.toString() "lastName" -> entity.lastName = entry.value?.toString() } } db.save(entity) } 

以上是很容易遵循的:

  • 我们没有validation请求值

以上可以通过在领域层对象上引入validation注解来缓解。 虽然在简单场景中这非常方便,但只要我们根据域对象的状态或执行更改的主体的angular色引入条件validation,就很不切实际。 更重要的是,在产品生存了一段时间之后,新的validation规则被引入后,仍然允许在非用户编辑上下文中更新实体。 在领域层上执行不variables似乎更实际一些,但保持边缘的validation 。

  • 在很多地方可能会非常相似

这实际上很容易解决,在80%的情况下,下面的工作:

 fun Map<String,Any?>.applyTo(entity:Any) { val entityEditor = BeanWrapperImpl(entity) forEach { entry -> if(entityEditor.isWritableProperty(entry.key)){ entityEditor.setPropertyValue(entry.key, entityEditor.convertForProperty(entry.value, entry.key)) } } } 

validation请求

感谢Kotlin中的委托属性,很容易在Map<String,Any?>基础上构build一个包装:

 class NameChangeRequest(val changes: Map<String, Any?> = mapOf()) { @get:NotBlank val firstName: String? by changes @get:NotBlank val lastName: String? by changes } 

使用Validator接口,我们可以过滤出与请求中不存在的属性相关的错误,如下所示:

 fun filterOutFieldErrorsNotPresentInTheRequest(target:Any, attributesFromRequest: Map<String, Any?>?, source: Errors): BeanPropertyBindingResult { val attributes = attributesFromRequest ?: emptyMap() return BeanPropertyBindingResult(target, source.objectName).apply { source.allErrors.forEach { e -> if (e is FieldError) { if (attributes.containsKey(e.field)) { addError(e) } } else { addError(e) } } } } 

显然我们可以使用HandlerMethodArgumentResolver来简化开发,我在下面做了。

最简单的解决scheme

我认为把上面描述的东西换成一个简单易用的图书馆是有道理的, 随着拼凑一个可以有一个强types的请求input模型以及声明性validation。 你所要做的就是导入configuration@Import(PatchyConfiguration::class)并在模型中实现PatchyRequest接口。

进一步阅读

  • spring同步
  • FGE / JSON-补丁

我有同样的问题,所以这里是我的经验/解决scheme。

我build议你实施该补丁,因为它应该是这样,如果

  • 一个键存在的值>值被设置
  • 一个键是空string>空string被设置
  • 一个键值为null>该字段被设置为null
  • 密钥不存在>该密钥的值不会更改

如果你不这样做,你很快就会得到一个很难理解的API。

所以我会放弃你的第一个select

同意客户,如果他想要删除一个属性,他应该给我一个空string(但是date和其他非stringtypes呢?)

在我看来,第二种select其实是一个很好的select。 这也是我们所做的(种)。

我不确定是否可以使validation属性与此选项一起工作,但是,如果validation不在您的域图层上, 这可能会从其他层处理的域中引发exception,并将其转换为错误的请求。

这是我们在一个应用程序中做到的:

 class PatchUserRequest { private boolean containsName = false; private String name; private boolean containsEmail = false; private String email; @Length(max = 100) // haven't tested this, but annotation is allowed on method, thus should work void setName(String name) { this.containsName = true; this.name = name; } boolean containsName() { return containsName; } String getName() { return name; } } ... 

json反序列化器将实例化PatchUserRequest,但它只会调用存在的字段的setter方法。 所以缺less字段的包含布尔值将保持为false。

在另一个应用程序,我们使用相同的原则,但有点不同。 (我更喜欢这个)

 class PatchUserRequest { private static final String NAME_KEY = "name"; private Map<String, ?> fields = new HashMap<>();; @Length(max = 100) // haven't tested this, but annotation is allowed on method, thus should work void setName(String name) { fields.put(NAME_KEY, name); } boolean containsName() { return fields.containsKey(NAME_KEY); } String getName() { return (String) fields.get(NAME_KEY); } } ... 

你也可以通过让你的PatchUserRequest扩展Map来做同样的事情。

另一个select可能是编写自己的json解串器,但是我没有自己尝试过。

有人可能会说这个例子中不应该使用PATCH,我应该使用PUT来更新我的用户。

我不同意这一点。 我也使用PATCH&PUT,就像你说的那样:

  • PUT – 用其整个表示更新对象(replace)
  • 修补程序 – 仅使用给定字段更新对象(更新)

正如您所指出的,主要问题是我们没有多个类似于null的值来区分显式和隐式的空值。 既然你标记了这个问题Kotlin我试图想出一个使用委托属性和属性引用的解决scheme。 其中一个重要的限制就是它对于Spring Boot使用的Jackson来说是透明的。

这个想法是通过使用委托属性自动存储哪些字段被显式设置为null的信息。

首先定义委托人:

 class ExpNull<R, T>(private val explicitNulls: MutableSet<KProperty<*>>) { private var v: T? = null operator fun getValue(thisRef: R, property: KProperty<*>) = v operator fun setValue(thisRef: R, property: KProperty<*>, value: T) { if (value == null) explicitNulls += property else explicitNulls -= property v = value } } 

这就像一个代理的属性,但存储在给定的MutableSet空属性。

现在在你的DTO

 class User { val explicitNulls = mutableSetOf<KProperty<*>>() var name: String? by ExpNull(explicitNulls) } 

用法是这样的:

 @Test fun `test with missing field`() { val json = "{}" val user = ObjectMapper().readValue(json, User::class.java) assertTrue(user.name == null) assertTrue(user.explicitNulls.isEmpty()) } @Test fun `test with explicit null`() { val json = "{\"name\": null}" val user = ObjectMapper().readValue(json, User::class.java) assertTrue(user.name == null) assertEquals(user.explicitNulls, setOf(User::name)) } 

这是因为Jackson在第二种情况下显式调用user.setName(null) ,而在第一种情况下省略了调用。

你当然可以多花点心思,并添加一些方法到你的DTO应该实现的接口。

 interface ExpNullable { val explicitNulls: Set<KProperty<*>> fun isExplicitNull(property: KProperty<*>) = property in explicitNulls } 

这使得user.isExplicitNull(User::name)的检查更好user.isExplicitNull(User::name)