介绍
对于专注于构建有效且可扩展的微服务的 java 开发人员来说,掌握 api 设计至关重要。本文概述了增强编码技能的最佳实践,并使用 java 示例来说明有效的技术与常见的错误。
1. 坚持restful原则
restful 架构依赖于无状态、可缓存性和统一接口等原则,促进一致的交互。
好示例:使用 post 请求创建新资源。
@restcontroller @requestmapping("/products") public class productcontroller { @postmapping public responseentity<product> createproduct(@requestbody product product) { product savedproduct = productservice.save(product); return responseentity.status(httpstatus.created).body(savedproduct); } } </product>
避免示例:使用 delete 请求检索资源。
@restcontroller @requestmapping("/products") public class productcontroller { @deletemapping("/{id}") public responseentity<product> getproduct(@pathvariable long id) { // incorrect; delete should not be used for retrieval. product product = productservice.findbyid(id); return responseentity.ok(product); } } </product>
2. 使用适当的 http 状态代码
http 状态代码对于向客户端传达请求结果至关重要。
好示例:成功删除资源时返回 204 no content。
@deletemapping("/{id}") public responseentity<void> deleteproduct(@pathvariable long id) { productservice.deletebyid(id); return responseentity.nocontent().build(); } </void>
避免 示例:由于资源不存在而导致删除失败,返回 200 ok。
@deletemapping("/{id}") public responseentity<void> deleteproduct(@pathvariable long id) { if (!productservice.existsbyid(id)) { return responseentity.ok().build(); // misleading response. } productservice.deletebyid(id); return responseentity.nocontent().build(); } </void>
3. 实施 api 版本控制
api 版本控制有助于在不中断现有用户的情况下管理变更,从而实现平稳过渡和更新。
立即学习“Java免费学习笔记(深入)”;
好示例:为了清楚起见,在 uri 中使用版本。
@restcontroller @requestmapping("/api/v2/orders") public class ordercontroller { // actions specific to version 2 of the orders api. }
避免示例:没有版本控制,这可能会破坏客户端实现。
@restcontroller @requestmapping("/orders") public class ordercontroller { // no versioning in place; risky for clients. }
4. 优雅地处理异常
有效的错误处理通过提供有意义的错误消息来增强用户体验。
好示例:无效输入场景的自定义异常处理程序。
@exceptionhandler(invalidinputexception.class) public responseentity<string> handleinvalidinput(invalidinputexception ex) { return responseentity.badrequest().body(ex.getmessage()); } </string>
避免示例:返回缺乏详细信息的通用错误消息。
@exceptionhandler(exception.class) public responseentity<string> handleallerrors(exception ex) { // bad practice; vague error message is unhelpful. return responseentity.status(httpstatus.internal_server_error).body("error occurred"); } </string>
5. api 设计中优先考虑安全性
安全至关重要; api 应强制执行身份验证和授权以保护敏感数据。
好示例:在访问资源之前检查用户权限。
@getmapping("/orders/{id}") public responseentity<order> getorderbyid(@pathvariable long id) { if (!authservice.haspermission("view_order", id)) { return responseentity.status(httpstatus.forbidden).build(); } order order = orderservice.findbyid(id); return order != null ? responseentity.ok(order) : responseentity.notfound().build(); } </order>
避免示例:忽视授权检查,面临未经授权访问的风险。
@getmapping("/orders/{id}") public responseentity<order> getorderbyid(@pathvariable long id) { // missing permission check; poses a security risk. order order = orderservice.findbyid(id); return responseentity.ok(order); } </order>
6. 维护清晰的 api 文档
完整的文档可以帮助开发人员了解如何有效地使用 api,从而促进集成的简便性。
好示例:使用 openapi 注释来获得清晰的文档。
@api(tags = "order management") @restcontroller @requestmapping("/api/v1/orders") public class ordercontroller { // actions documented with openapi annotations. }
避免示例:缺乏文档,导致 api 难以导航。
@restcontroller @requestmapping("/orders") public class ordercontroller { // actions without any documentation or comments. }
7. 明智地使用查询参数
查询参数允许客户端对结果进行过滤、排序和分页,从而增强灵活性。
好示例:支持分页和过滤的端点。
@getmapping("/products") public responseentity<list>> getproducts( @requestparam optional<string> category, @requestparam(defaultvalue = "0") int page, @requestparam(defaultvalue = "10") int size) { list<product> products = productservice.findproducts(category, page, size); return responseentity.ok(products); } </product></string></list>
避免示例:返回大型数据集而不进行任何过滤或分页。
@getmapping("/products") public responseentity<list>> getallproducts() { return responseentity.ok(productservice.findall()); // excessive data returned. } </list>
8. 实施 http 缓存策略
缓存通过最小化服务器负载和响应时间来提高性能。
好示例:使用缓存控制标头来优化响应。
@getmapping("/products/{id}") public responseentity<product> getproductbyid(@pathvariable long id) { product product = productservice.findbyid(id); return responseentity.ok() .cachecontrol(cachecontrol.maxage(30, timeunit.seconds)) .body(product); } </product>
避免示例:未能利用缓存标头,导致冗余数据传输。
@getmapping("/products/{id}") public responseentity<product> getproductbyid(@pathvariable long id) { return responseentity.ok(productservice.findbyid(id)); // no caching utilized. } </product>
9. 确保直观的 api 设计
api 应该简单、自描述,并具有逻辑命名约定。
好示例:使用清晰且描述性的端点名称。
@postmapping("/users") public responseentity<user> registeruser(@requestbody user user) { // clearly indicates user registration. } @getmapping("/users/{id}") public responseentity<user> fetchuserbyid(@pathvariable long id) { // clearly indicates fetching a user by id. } </user></user>
避免示例:令人困惑的端点路径掩盖了其目的。
@putmapping("/updateuserinfo") public responseentity<user> updateuser(@requestbody user user) { // unclear path; doesn't specify the resource being updated. } </user>
10.启用响应压缩
通过响应压缩优化有效负载大小可提高性能。
好示例:配置服务器以启用 gzip 压缩。
propertiescopy code# in spring boot application.properties server.compression.enabled=true server.compression.mime-types=application/json,text/html
避免示例:发送大响应而不压缩,增加加载时间。
@getmapping("/products") public responseentity<list>> getallproducts() { return responseentity.ok(productservice.findall()); // large payload without compression. } </list>
11.拥抱异步处理
异步操作对于管理长时间运行的任务而不阻塞客户端至关重要。
很好示例:使用异步处理处理批量请求。
@postmapping("/orders/batch") public responseentity<void> batchcreateorders(@requestbody list<order> orders) { completablefuture<void> future = orderservice.createordersasync(orders); httpheaders headers = new httpheaders(); headers.setlocation(uri.create("/orders/batch/status")); return responseentity.accepted().headers(headers).build(); } </void></order></void>
避免示例:同步处理使客户端等待长时间操作。
@PostMapping("/orders/batch") public ResponseEntity<list>> batchCreateOrders(@RequestBody List<order> orders) { List<order> createdOrders = orderService.createOrders(orders); // This could block. return ResponseEntity.ok(createdOrders); } </order></order></list>
结论
通过应用这些最佳实践,开发人员可以创建健壮、可维护且用户友好的 api。这种方法不仅有助于构建高质量的 api,还确保它们可以随着时间的推移而发展,而不会对客户造成干扰。
参考
- restful web api 设计
- gitlab api 设计指南
- rest 架构约束
- 标准响应状态代码
- api 风格指南
- 学习 rest api 设计
以上就是Java API 设计的关键最佳实践的详细内容,更多请关注php中文网其它相关文章!