{"id":203213,"date":"2025-05-22T13:18:56","date_gmt":"2025-05-22T05:18:56","guid":{"rendered":"https:\/\/server.hk\/cnblog\/203213\/"},"modified":"2025-05-22T13:18:56","modified_gmt":"2025-05-22T05:18:56","slug":"java-api-%e8%ae%be%e8%ae%a1%e7%9a%84%e5%85%b3%e9%94%ae%e6%9c%80%e4%bd%b3%e5%ae%9e%e8%b7%b5","status":"publish","type":"post","link":"https:\/\/server.hk\/cnblog\/203213\/","title":{"rendered":"Java API \u8bbe\u8ba1\u7684\u5173\u952e\u6700\u4f73\u5b9e\u8df5"},"content":{"rendered":"

<\/b> <\/p>\n

Java API \u8bbe\u8ba1\u7684\u5173\u952e\u6700\u4f73\u5b9e\u8df5<\/h1>\n

<\/i>\u6536\u85cf<\/span> <\/p>\n

\u5b66\u4e60\u77e5\u8bc6\u8981\u5584\u4e8e\u601d\u8003\uff0c\u601d\u8003\uff0c\u518d\u601d\u8003\uff01\u4eca\u5929\u5c0f\u7f16\u5c31\u7ed9\u5927\u5bb6\u5e26\u6765\u300aJava API \u8bbe\u8ba1\u7684\u5173\u952e\u6700\u4f73\u5b9e\u8df5\u300b<\/span>\uff0c\u4ee5\u4e0b\u5185\u5bb9\u4e3b\u8981\u5305\u542b<\/span>\u7b49\u77e5\u8bc6\u70b9\uff0c\u5982\u679c\u4f60\u6b63\u5728\u5b66\u4e60\u6216\u51c6\u5907\u5b66\u4e60\u6587\u7ae0<\/span>\uff0c\u5c31\u90fd\u4e0d\u8981\u9519\u8fc7\u672c\u6587\u5566~\u8ba9\u6211\u4eec\u4e00\u8d77\u6765\u770b\u770b\u5427\uff0c\u80fd\u5e2e\u52a9\u5230\u4f60\u5c31\u66f4\u597d\u4e86\uff01<\/span><\/p>\n

<\/p>\n

\u4ecb\u7ecd <\/h3>\n

\u5bf9\u4e8e\u4e13\u6ce8\u4e8e\u6784\u5efa\u6709\u6548\u4e14\u53ef\u6269\u5c55\u7684\u5fae\u670d\u52a1\u7684 java \u5f00\u53d1\u4eba\u5458\u6765\u8bf4\uff0c\u638c\u63e1 api \u8bbe\u8ba1\u81f3\u5173\u91cd\u8981\u3002\u672c\u6587\u6982\u8ff0\u4e86\u589e\u5f3a\u7f16\u7801\u6280\u80fd\u7684\u6700\u4f73\u5b9e\u8df5\uff0c\u5e76\u4f7f\u7528 java \u793a\u4f8b\u6765\u8bf4\u660e\u6709\u6548\u7684\u6280\u672f\u4e0e\u5e38\u89c1\u7684\u9519\u8bef\u3002<\/p>\n

1. \u575a\u6301restful\u539f\u5219 <\/h3>\n

restful \u67b6\u6784\u4f9d\u8d56\u4e8e\u65e0\u72b6\u6001\u3001\u53ef\u7f13\u5b58\u6027\u548c\u7edf\u4e00\u63a5\u53e3\u7b49\u539f\u5219\uff0c\u4fc3\u8fdb\u4e00\u81f4\u7684\u4ea4\u4e92\u3002<\/p>\n

\u597d<\/strong>\u793a\u4f8b\uff1a\u4f7f\u7528 post \u8bf7\u6c42\u521b\u5efa\u65b0\u8d44\u6e90\u3002<\/p>\n

@restcontroller\n@requestmapping(\"\/products\")\npublic class productcontroller {\n\n    @postmapping\n    public responseentity<product> createproduct(@requestbody product product) {\n        product savedproduct = productservice.save(product);\n        return responseentity.status(httpstatus.created).body(savedproduct);\n    }\n}\n<\/pre>\n
\u907f\u514d<\/strong>\u793a\u4f8b\uff1a\u4f7f\u7528 delete \u8bf7\u6c42\u68c0\u7d22\u8d44\u6e90\u3002<\/p>\n
@restcontroller\n@requestmapping(\"\/products\")\npublic class productcontroller {\n\n    @deletemapping(\"\/{id}\")\n    public responseentity<product> getproduct(@pathvariable long id) {\n        \/\/ incorrect; delete should not be used for retrieval.\n        product product = productservice.findbyid(id);\n        return responseentity.ok(product);\n    }\n}\n<\/pre>\n
 2. \u4f7f\u7528\u9002\u5f53\u7684 http \u72b6\u6001\u4ee3\u7801 <\/h3>\n
http \u72b6\u6001\u4ee3\u7801\u5bf9\u4e8e\u5411\u5ba2\u6237\u7aef\u4f20\u8fbe\u8bf7\u6c42\u7ed3\u679c\u81f3\u5173\u91cd\u8981\u3002<\/p>\n
\u597d<\/strong>\u793a\u4f8b\uff1a\u6210\u529f\u5220\u9664\u8d44\u6e90\u65f6\u8fd4\u56de 204 no content\u3002<\/p>\n
@deletemapping(\"\/{id}\")\npublic responseentity<void> deleteproduct(@pathvariable long id) {\n    productservice.deletebyid(id);\n    return responseentity.nocontent().build();\n}\n<\/pre>\n
\u907f\u514d<\/strong> \u793a\u4f8b\uff1a\u7531\u4e8e\u8d44\u6e90\u4e0d\u5b58\u5728\u800c\u5bfc\u81f4\u5220\u9664\u5931\u8d25\uff0c\u8fd4\u56de 200 ok\u3002<\/p>\n
@deletemapping(\"\/{id}\")\npublic responseentity<void> deleteproduct(@pathvariable long id) {\n    if (!productservice.existsbyid(id)) {\n        return responseentity.ok().build(); \/\/ misleading response.\n    }\n    productservice.deletebyid(id);\n    return responseentity.nocontent().build();\n}\n<\/pre>\n
 3. \u5b9e\u65bd api \u7248\u672c\u63a7\u5236 <\/h3>\n
api \u7248\u672c\u63a7\u5236\u6709\u52a9\u4e8e\u5728\u4e0d\u4e2d\u65ad\u73b0\u6709\u7528\u6237\u7684\u60c5\u51b5\u4e0b\u7ba1\u7406\u53d8\u66f4\uff0c\u4ece\u800c\u5b9e\u73b0\u5e73\u7a33\u8fc7\u6e21\u548c\u66f4\u65b0\u3002<\/p>\n
\u597d<\/strong>\u793a\u4f8b\uff1a\u4e3a\u4e86\u6e05\u695a\u8d77\u89c1\uff0c\u5728 uri \u4e2d\u4f7f\u7528\u7248\u672c\u3002<\/p>\n
@restcontroller\n@requestmapping(\"\/api\/v2\/orders\")\npublic class ordercontroller {\n    \/\/ actions specific to version 2 of the orders api.\n}\n<\/pre>\n
\u907f\u514d<\/strong>\u793a\u4f8b\uff1a\u6ca1\u6709\u7248\u672c\u63a7\u5236\uff0c\u8fd9\u53ef\u80fd\u4f1a\u7834\u574f\u5ba2\u6237\u7aef\u5b9e\u73b0\u3002<\/p>\n
@restcontroller\n@requestmapping(\"\/orders\")\npublic class ordercontroller {\n    \/\/ no versioning in place; risky for clients.\n}\n<\/pre>\n
 4. \u4f18\u96c5\u5730\u5904\u7406\u5f02\u5e38 <\/h3>\n
\u6709\u6548\u7684\u9519\u8bef\u5904\u7406\u901a\u8fc7\u63d0\u4f9b\u6709\u610f\u4e49\u7684\u9519\u8bef\u6d88\u606f\u6765\u589e\u5f3a\u7528\u6237\u4f53\u9a8c\u3002<\/p>\n
\u597d<\/strong>\u793a\u4f8b\uff1a\u65e0\u6548\u8f93\u5165\u573a\u666f\u7684\u81ea\u5b9a\u4e49\u5f02\u5e38\u5904\u7406\u7a0b\u5e8f\u3002<\/p>\n
@exceptionhandler(invalidinputexception.class)\npublic responseentity<string> handleinvalidinput(invalidinputexception ex) {\n    return responseentity.badrequest().body(ex.getmessage());\n}\n<\/pre>\n
\u907f\u514d<\/strong>\u793a\u4f8b\uff1a\u8fd4\u56de\u7f3a\u4e4f\u8be6\u7ec6\u4fe1\u606f\u7684\u901a\u7528\u9519\u8bef\u6d88\u606f\u3002<\/p>\n
@exceptionhandler(exception.class)\npublic responseentity<string> handleallerrors(exception ex) {\n    \/\/ bad practice; vague error message is unhelpful.\n    return responseentity.status(httpstatus.internal_server_error).body(\"error occurred\");\n}\n<\/pre>\n
 5. api \u8bbe\u8ba1\u4e2d\u4f18\u5148\u8003\u8651\u5b89\u5168\u6027 <\/h3>\n
\u5b89\u5168\u81f3\u5173\u91cd\u8981\uff1b api \u5e94\u5f3a\u5236\u6267\u884c\u8eab\u4efd\u9a8c\u8bc1\u548c\u6388\u6743\u4ee5\u4fdd\u62a4\u654f\u611f\u6570\u636e\u3002<\/p>\n
\u597d<\/strong>\u793a\u4f8b\uff1a\u5728\u8bbf\u95ee\u8d44\u6e90\u4e4b\u524d\u68c0\u67e5\u7528\u6237\u6743\u9650\u3002<\/p>\n
@getmapping(\"\/orders\/{id}\")\npublic responseentity<order> getorderbyid(@pathvariable long id) {\n    if (!authservice.haspermission(\"view_order\", id)) {\n        return responseentity.status(httpstatus.forbidden).build();\n    }\n\n    order order = orderservice.findbyid(id);\n    return order != null ? responseentity.ok(order) : responseentity.notfound().build();\n}\n<\/pre>\n
\u907f\u514d<\/strong>\u793a\u4f8b\uff1a\u5ffd\u89c6\u6388\u6743\u68c0\u67e5\uff0c\u9762\u4e34\u672a\u7ecf\u6388\u6743\u8bbf\u95ee\u7684\u98ce\u9669\u3002<\/p>\n
@getmapping(\"\/orders\/{id}\")\npublic responseentity<order> getorderbyid(@pathvariable long id) {\n    \/\/ missing permission check; poses a security risk.\n\n    order order = orderservice.findbyid(id);\n    return responseentity.ok(order);\n}\n<\/pre>\n
 6. \u7ef4\u62a4\u6e05\u6670\u7684 api \u6587\u6863 <\/h3>\n
\u5b8c\u6574\u7684\u6587\u6863\u53ef\u4ee5\u5e2e\u52a9\u5f00\u53d1\u4eba\u5458\u4e86\u89e3\u5982\u4f55\u6709\u6548\u5730\u4f7f\u7528 api\uff0c\u4ece\u800c\u4fc3\u8fdb\u96c6\u6210\u7684\u7b80\u4fbf\u6027\u3002<\/p>\n
\u597d<\/strong>\u793a\u4f8b\uff1a\u4f7f\u7528 openapi \u6ce8\u91ca\u6765\u83b7\u5f97\u6e05\u6670\u7684\u6587\u6863\u3002<\/p>\n
@api(tags = \"order management\")\n@restcontroller\n@requestmapping(\"\/api\/v1\/orders\")\npublic class ordercontroller {\n    \/\/ actions documented with openapi annotations.\n}\n<\/pre>\n
\u907f\u514d<\/strong>\u793a\u4f8b\uff1a\u7f3a\u4e4f\u6587\u6863\uff0c\u5bfc\u81f4 api \u96be\u4ee5\u5bfc\u822a\u3002<\/p>\n
@restcontroller\n@requestmapping(\"\/orders\")\npublic class ordercontroller {\n    \/\/ actions without any documentation or comments.\n}\n<\/pre>\n
 7. \u660e\u667a\u5730\u4f7f\u7528\u67e5\u8be2\u53c2\u6570 <\/h3>\n
\u67e5\u8be2\u53c2\u6570\u5141\u8bb8\u5ba2\u6237\u7aef\u5bf9\u7ed3\u679c\u8fdb\u884c\u8fc7\u6ee4\u3001\u6392\u5e8f\u548c\u5206\u9875\uff0c\u4ece\u800c\u589e\u5f3a\u7075\u6d3b\u6027\u3002<\/p>\n
\u597d<\/strong>\u793a\u4f8b\uff1a\u652f\u6301\u5206\u9875\u548c\u8fc7\u6ee4\u7684\u7aef\u70b9\u3002<\/p>\n
@getmapping(\"\/products\")\npublic responseentity<list<product>> getproducts(\n        @requestparam optional<string> category,\n        @requestparam(defaultvalue = \"0\") int page,\n        @requestparam(defaultvalue = \"10\") int size) {\n    list<product> products = productservice.findproducts(category, page, size);\n    return responseentity.ok(products);\n}\n<\/pre>\n
\u907f\u514d<\/strong>\u793a\u4f8b\uff1a\u8fd4\u56de\u5927\u578b\u6570\u636e\u96c6\u800c\u4e0d\u8fdb\u884c\u4efb\u4f55\u8fc7\u6ee4\u6216\u5206\u9875\u3002<\/p>\n
@getmapping(\"\/products\")\npublic responseentity<list<product>> getallproducts() {\n    return responseentity.ok(productservice.findall()); \/\/ excessive data returned.\n}\n<\/pre>\n
 8. \u5b9e\u65bd http \u7f13\u5b58\u7b56\u7565 <\/h3>\n
\u7f13\u5b58\u901a\u8fc7\u6700\u5c0f\u5316\u670d\u52a1\u5668\u8d1f\u8f7d\u548c\u54cd\u5e94\u65f6\u95f4\u6765\u63d0\u9ad8\u6027\u80fd\u3002<\/p>\n
\u597d<\/strong>\u793a\u4f8b\uff1a\u4f7f\u7528\u7f13\u5b58\u63a7\u5236\u6807\u5934\u6765\u4f18\u5316\u54cd\u5e94\u3002<\/p>\n
@getmapping(\"\/products\/{id}\")\npublic responseentity<product> getproductbyid(@pathvariable long id) {\n    product product = productservice.findbyid(id);\n    return responseentity.ok()\n            .cachecontrol(cachecontrol.maxage(30, timeunit.seconds))\n            .body(product);\n}\n<\/pre>\n
\u907f\u514d<\/strong>\u793a\u4f8b\uff1a\u672a\u80fd\u5229\u7528\u7f13\u5b58\u6807\u5934\uff0c\u5bfc\u81f4\u5197\u4f59\u6570\u636e\u4f20\u8f93\u3002<\/p>\n
@getmapping(\"\/products\/{id}\")\npublic responseentity<product> getproductbyid(@pathvariable long id) {\n    return responseentity.ok(productservice.findbyid(id)); \/\/ no caching utilized.\n}\n<\/pre>\n
 9. \u786e\u4fdd\u76f4\u89c2\u7684 api \u8bbe\u8ba1 <\/h3>\n
api \u5e94\u8be5\u7b80\u5355\u3001\u81ea\u63cf\u8ff0\uff0c\u5e76\u5177\u6709\u903b\u8f91\u547d\u540d\u7ea6\u5b9a\u3002<\/p>\n
\u597d<\/strong>\u793a\u4f8b\uff1a\u4f7f\u7528\u6e05\u6670\u4e14\u63cf\u8ff0\u6027\u7684\u7aef\u70b9\u540d\u79f0\u3002<\/p>\n
@postmapping(\"\/users\")\npublic responseentity<user> registeruser(@requestbody user user) {\n    \/\/ clearly indicates user registration.\n}\n\n@getmapping(\"\/users\/{id}\")\npublic responseentity<user> fetchuserbyid(@pathvariable long id) {\n    \/\/ clearly indicates fetching a user by id.\n}\n<\/pre>\n
\u907f\u514d<\/strong>\u793a\u4f8b\uff1a\u4ee4\u4eba\u56f0\u60d1\u7684\u7aef\u70b9\u8def\u5f84\u63a9\u76d6\u4e86\u5176\u76ee\u7684\u3002<\/p>\n
@putmapping(\"\/updateuserinfo\")\npublic responseentity<user> updateuser(@requestbody user user) {\n    \/\/ unclear path; doesn't specify the resource being updated.\n}\n<\/pre>\n
 10.\u542f\u7528\u54cd\u5e94\u538b\u7f29 <\/h3>\n
\u901a\u8fc7\u54cd\u5e94\u538b\u7f29\u4f18\u5316\u6709\u6548\u8d1f\u8f7d\u5927\u5c0f\u53ef\u63d0\u9ad8\u6027\u80fd\u3002<\/p>\n
\u597d<\/strong>\u793a\u4f8b\uff1a\u914d\u7f6e\u670d\u52a1\u5668\u4ee5\u542f\u7528 gzip \u538b\u7f29\u3002<\/p>\n
propertiescopy code# in spring boot application.properties\nserver.compression.enabled=true\nserver.compression.mime-types=application\/json,text\/html\n<\/pre>\n
\u907f\u514d<\/strong>\u793a\u4f8b\uff1a\u53d1\u9001\u5927\u54cd\u5e94\u800c\u4e0d\u538b\u7f29\uff0c\u589e\u52a0\u52a0\u8f7d\u65f6\u95f4\u3002<\/p>\n
@getmapping(\"\/products\")\npublic responseentity<list<product>> getallproducts() {\n    return responseentity.ok(productservice.findall()); \/\/ large payload without compression.\n}\n<\/pre>\n
 11.\u62e5\u62b1\u5f02\u6b65\u5904\u7406 <\/h3>\n
\u5f02\u6b65\u64cd\u4f5c\u5bf9\u4e8e\u7ba1\u7406\u957f\u65f6\u95f4\u8fd0\u884c\u7684\u4efb\u52a1\u800c\u4e0d\u963b\u585e\u5ba2\u6237\u7aef\u81f3\u5173\u91cd\u8981\u3002<\/p>\n
\u5f88\u597d<\/strong>\u793a\u4f8b\uff1a\u4f7f\u7528\u5f02\u6b65\u5904\u7406\u5904\u7406\u6279\u91cf\u8bf7\u6c42\u3002<\/p>\n
@postmapping(\"\/orders\/batch\")\npublic responseentity<void> batchcreateorders(@requestbody list<order> orders) {\n    completablefuture<void> future = orderservice.createordersasync(orders);\n    httpheaders headers = new httpheaders();\n    headers.setlocation(uri.create(\"\/orders\/batch\/status\"));\n    return responseentity.accepted().headers(headers).build();\n}\n<\/pre>\n
\u907f\u514d<\/strong>\u793a\u4f8b\uff1a\u540c\u6b65\u5904\u7406\u4f7f\u5ba2\u6237\u7aef\u7b49\u5f85\u957f\u65f6\u95f4\u64cd\u4f5c\u3002<\/p>\n
@PostMapping(\"\/orders\/batch\")\npublic ResponseEntity<List<Order>> batchCreateOrders(@RequestBody List<Order> orders) {\n    List<Order> createdOrders = orderService.createOrders(orders);  \/\/ This could block.\n    return ResponseEntity.ok(createdOrders);\n}\n<\/pre>\n
 \u7ed3\u8bba <\/h3>\n
\u901a\u8fc7\u5e94\u7528\u8fd9\u4e9b\u6700\u4f73\u5b9e\u8df5\uff0c\u5f00\u53d1\u4eba\u5458\u53ef\u4ee5\u521b\u5efa\u5065\u58ee\u3001\u53ef\u7ef4\u62a4\u4e14\u7528\u6237\u53cb\u597d\u7684 api\u3002\u8fd9\u79cd\u65b9\u6cd5\u4e0d\u4ec5\u6709\u52a9\u4e8e\u6784\u5efa\u9ad8\u8d28\u91cf\u7684 api\uff0c\u8fd8\u786e\u4fdd\u5b83\u4eec\u53ef\u4ee5\u968f\u7740\u65f6\u95f4\u7684\u63a8\u79fb\u800c\u53d1\u5c55\uff0c\u800c\u4e0d\u4f1a\u5bf9\u5ba2\u6237\u9020\u6210\u5e72\u6270\u3002<\/p>\n
 \u53c2\u8003 <\/h3>\n
    \n
  • restful web api \u8bbe\u8ba1<\/li>\n
  • gitlab api \u8bbe\u8ba1\u6307\u5357<\/li>\n
  • rest \u67b6\u6784\u7ea6\u675f<\/li>\n
  • \u6807\u51c6\u54cd\u5e94\u72b6\u6001\u4ee3\u7801<\/li>\n
  • api \u98ce\u683c\u6307\u5357<\/li>\n
  • \u5b66\u4e60 rest api \u8bbe\u8ba1<\/li>\n<\/ul>\n
    \u7406\u8bba\u8981\u638c\u63e1\uff0c\u5b9e\u64cd\u4e0d\u80fd\u843d\uff01\u4ee5\u4e0a\u5173\u4e8e\u300aJava API \u8bbe\u8ba1\u7684\u5173\u952e\u6700\u4f73\u5b9e\u8df5\u300b\u7684\u8be6\u7ec6\u4ecb\u7ecd\uff0c\u5927\u5bb6\u90fd\u638c\u63e1\u4e86\u5427\uff01\u5982\u679c\u60f3\u8981\u7ee7\u7eed\u63d0\u5347\u81ea\u5df1\u7684\u80fd\u529b\uff0c\u90a3\u4e48\u5c31\u6765\u5173\u6ce8\u516c\u4f17\u53f7\u5427\uff01<\/p>\n
          \u7248\u672c\u58f0\u660e \u672c\u6587\u8f6c\u8f7d\u4e8e\uff1adev.to \u5982\u6709\u4fb5\u72af\uff0c\u8bf7\u8054\u7cfb\u5220\u9664<\/p>\n","protected":false},"excerpt":{"rendered":"
    Java API \u8bbe\u8ba1\u7684\u5173\u952e\u6700\u4f73...<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"closed","ping_status":"","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[4925],"tags":[],"class_list":["post-203213","post","type-post","status-publish","format-standard","hentry","category-4925"],"_links":{"self":[{"href":"https:\/\/server.hk\/cnblog\/wp-json\/wp\/v2\/posts\/203213","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/server.hk\/cnblog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/server.hk\/cnblog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/server.hk\/cnblog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/server.hk\/cnblog\/wp-json\/wp\/v2\/comments?post=203213"}],"version-history":[{"count":0,"href":"https:\/\/server.hk\/cnblog\/wp-json\/wp\/v2\/posts\/203213\/revisions"}],"wp:attachment":[{"href":"https:\/\/server.hk\/cnblog\/wp-json\/wp\/v2\/media?parent=203213"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/server.hk\/cnblog\/wp-json\/wp\/v2\/categories?post=203213"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/server.hk\/cnblog\/wp-json\/wp\/v2\/tags?post=203213"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}