تقدم هذه المقالة أفضل الممارسات لـ Spring Boot لتطوير واجهات REST ومشاركتها معك ، على النحو التالي:
تتوافق أفعال HTTP مع أوامر SQL
يحصل
الحصول على الموارد من الخادم ، يمكنك الحصول على موارد واحدة أو أكثر ، والحصول على جميع معلومات المستخدم على الخادم ، GET /USER /ID ، المعرف المحدد ، والحصول على معلومات المستخدم للمعرف المحدد.
بريد
قم بإنشاء مورد جديد على الخادم ، يتوافق مع CreatePost /المستخدمين في أمر SQL لإنشاء مستخدم جديد
يضع
قم بتحديث مورد على الخادم ، ويوفر العميل المورد الكامل الذي تم تغييره ، المقابل لـ UpdatePut /user /id في أمر SQL لتحديث جميع المعلومات الخاصة بالمستخدم بالمعرف المحدد
يمسح
احذف مورد من الخادم ، وحذف معلومات المستخدم الخاصة بالمعرف المحدد المقابل لـ DeletEdelete /Usere /id في أمر SQL
رقعة
قم بتحديث بعض سمات مورد على الخادم ، المقابلة لـ UpdatePatch /User /id في أمر SQL لتحديث سمة معينة من المستخدم بالمعرف المحدد
اتفاقيات في عناوين URL
الأسماء في عناوين URL تستخدم أشكال الجمع
كان مسألة ما إذا كان الاسم الموجود في عنوان URL يستخدم فرديًا أو صيغة الجمع مثيرة للجدل. تتوافق الأسماء الموجودة في عنوان URL بشكل عام مع الجداول الموجودة في قاعدة البيانات ، وتخزن الجداول بيانات مماثلة. في الممارسة العملية ، أجبر على استخدام أشكال الجمع ، والتي تبدو أكثر راحة.
/المستخدمين/المستخدمين/1/أدوار/أدوار/أدوار/1
أما بالنسبة لبعض الأسماء غير المنتظمة التي لا يمكن فهمها ، فإن ذلك يعتمد على رأيك.
/أبطال/أبطال/1/أشخاص/أشخاص/1/قدم/1/قدم/قدم/1/قدم/قدم/1
إصدار
تحدث أرقام الإصدار لإضافتها إلى عنوان URL للتعامل مع التغييرات غير المتوافقة والمدمرة. عند إطلاق واجهة برمجة تطبيقات جديدة ، يمكن للعميل الانتقال إلى واجهة برمجة التطبيقات الجديدة بحرية ولن يكون في مشكلة بسبب استدعاء واجهة برمجة تطبيقات جديدة تمامًا. استخدم بادئة "V" البديهية للإشارة إلى أن الرقم التالي هو رقم الإصدار ، ولا يلزم رقم إصدار ثانوي ، ويجب عدم إصدار إصدارات API بشكل متكرر.
/edu/v1/user/edu/v1/roles
استخدم سلاسل الاستعلام للمعلمات الاختيارية المعقدة
من أجل جعل عنوان URL أصغر وأكثر إيجازًا ، يتم تعيين عنوان URL الأساسي للمورد ، ويتم تمثيل المعلمات الاختيارية والمعقدة بسلاسل الاستعلام.
/edu/v1/user؟ تم تمكين = 1 & rolyid = 1
توفير معلومات الترحيل
ليس من الجيد إرجاع جميع الموارد في قاعدة البيانات في وقت واحد ، لذلك مطلوب آلية ترحيل. عادة ، يتم استخدام المعلمات المعروفة في قاعدة البيانات لتعويض والحد
/edu/v1/user؟ usabled = 1 & offset = 1 & limit = 15
إذا لم يمر العميل هذه المعلمات ، فيجب استخدام القيمة الافتراضية ، وعادة ما يكون الإزاحة = 0 ، الحد = 10.
استخدم الأفعال لطلبات غير الموارد
في بعض الأحيان ، لا تتضمن مكالمات API الموارد ، وفي هذه الحالة يقوم الخادم بإجراء عملية وإرجاع النتيجة إلى العميل.
/edu/v1/calc؟ p = 100
النظر في موارد محددة وعمليات البحث عبر الموارد
من السهل تقديم البحث عن نهاية محددة. تحتاج فقط إلى استخدام مجموعة الموارد المقابلة وإلحاق سلسلة البحث بمعلمات الاستعلام.
/edu/v1/user؟ اسم المستخدم = li Qinghai
إذا كنت بحاجة إلى تقديم بحث عالمي عن جميع الموارد ، فأنت بحاجة إلى استخدام طريقة أخرى.
/edu/v1/search؟ key = li Qinghai
نتائج الاستجابة
استخدم تسميات الجمل الصغيرة كمعرف سمة
عادةً ما يتم استخدام خدمات الويب RESTful من قبل العملاء المكتوبة في JavaScript. يقوم العميل بتحويل استجابة JSON إلى كائن JavaScript ثم يستدعي خصائصه. لذلك ، من الأفضل اتباع المواصفات الشائعة لبرنامج JavaScript.
شخص
توفير معلومات الترحيل
عندما يتم إرجاع العديد من النتائج ، يجب توفير معلومات الترحيل.
{"page": 0 ، "size": 10 ، "Total": 3465 ، "OBJ": []}واجهة راحة تطوير الربيع MVC
التعليقات التوضيحية المشتركة
RestController
RestController هو توضيح مزيج من ResponseBody و Controller.
requestmapping
يمكن تطبيق هذا التعليق على طريقة وحدة التحكم أو على فئة وحدة التحكم هذه. عندما تضيف وحدة التحكم تعليق توضيحي requestmapping على مستوى الفصل ، يتم تطبيق هذا التعليق على جميع أساليب المعالج لوحدة التحكم. سوف يكمل التعليق التوضيحي @requestmapping على طريقة المعالج إعلان requestmapping على مستوى الفصل.
postmapping
التعليق التوضيحي المركب هو اختصار @requestmapping (method = requestMethod.post).
putmapping
التعليق التوضيحي المركب هو اختصار @requestmapping (method = requestMethod.put).
patchMapping
التعليق التوضيحي المركب هو اختصار @requestmapping (method = requestMethod.patch).
deletemapping
التعليق التوضيحي المركب هو اختصار @requestmapping (method = requestMethod.delete).
getMapping
التعليق التوضيحي المركب هو اختصار @requestmapping (method = requestMethod.get).
pathvariable
الحصول على البيانات في عنوان URL.
requestparam
يحصل على قيمة المعلمة المطلوبة.
REST واجهة ومثال وثائق API Swagger
لاستخدام Swagger ، يرجى الرجوع إلى استخدام Swagger2 في مشروع Boot Spring. الرمز في الطريقة غير مهم ، المهم هو توقيع الطريقة والتعيين مع أفعال HTTP.
استيراد java.util.date ؛ استيراد javax.persistence.entitynotfoundException ؛ استيراد org.springframework.beans.factory.annotation. org.springframework.web.bind.annotation.patchMapping ؛ استيراد org.springframework.web.bind.annotation.pathvariable ؛ استيراد org.springframework.web.bind.annotation.postmapping org.springframework.web.bind.annotation.requestmapping ؛ استيراد org.springframework.web.bind.annotation.requestparam ؛ استيراد org.springframework.web.bind.annotation.restController cn.com.infcn.jianshu.exception.bizexception ؛ import cn.com.infcn.jianshu.exception.loginnameorpassworderRorexception ؛ import cn.com.infcn.jianshu.Exception.ResourceExistsexte cn.com.infcn.jianshu.util.jsonresult ؛ import io.swagger.annotations.api ؛ import io.swagger.annotations.apiparam ؛/** * system user controller * *@author li qinghai */@api (value = value = styper user interface "، tags = فئة USERCONTROLLER /** * إضافة مستخدم ، سجل * * param logInname * حساب تسجيل الدخول * param username * اسم المستخدم * param password * تسجيل الدخول إلى كلمة مرور * param rolid * دور المستخدم * return * throws ResourceExiStception */apiOperation (value = "login = loginname (loginname) مطلوب = صواب) @requestparam (مطلوب = صواب) @ @requestbody سلسلة logInName ، apiParam (name = "username" ، value = "username" ، required = true) requestparam (regue = true) @stringrequestparam ، @appiparam (name = "value =" تسجيل الدخول إلى ". apiParam (name = "roalId" ، value = "رقم دور المستخدم" ، مطلوب = صواب) requestparam (مطلوب = صواب) @requestbody string rowiD) يلقي ResourceExistsexception {boolean موجود = this.userservice.exists (loginName) ؛ إذا (موجود) {رمي New ResourceExiStSexception (logInName) ؛ } user user = userservice.create (logInName ، كلمة المرور ، اسم المستخدم ، rolyId) ؛ إرجاع jsonresult.success (المستخدم) ؛ }/** * تسجيل الدخول المستخدم مع حساب تسجيل الدخول وكلمة مرور تسجيل الدخول * * param loginname * حساب تسجيل الدخول * param password * login password * throws entitynotfoundException */apiOperation (value = "Query user information on or or or or explication) requestparam (مطلوب = صواب) سلسلة loginname ، apiParam (name = "password" ، value = "login password" ، required = true) @requestparam (required = true) string password) remOws LoginNamePassWorderRorexception {user user = this.userservice.login (loginname ، password) ؛ if (null == user) {رمي loginNamePassWorderRorexception () ؛ } إرجاع jsonresult.success (المستخدم) ؛ }/** * Query معلومات المستخدم استنادًا إلى رقم المستخدم * * param معرف * رقم المستخدم * throws entitynotfoundException */apiOperation (value = "معلومات مستخدم Query استنادًا إلى رقم المستخدم") getMapping ("/{id}") entitynotfoundException {user user = this.userservice.getone (id) ؛ إرجاع jsonresult.success (المستخدم) ؛ }/** * يتم إلغاء الحساب ، ولا يتم حذف بيانات المستخدم * * param userid * رقم المستخدم * regurn */apiOperation (value = "carded Out of Account") patchMapping ("/{id}") entitynotfoundException {this.userservice.cancel (id) ؛ إرجاع jsonresult.success () ؛ }/** * إعادة تعيين كلمة المرور * * param معرف * رقم المستخدم * param password * كلمة مرور تسجيل الدخول الجديدة * return */apiOperation (value = "reset password") patchMapping ("/") public jsonresult updatePasspars (apiParam (name = "id" "كلمة المرور" ، value = "كلمة مرور تسجيل الدخول الجديدة" ، مطلوب = صواب) @requestparam (مطلوب = صحيح) كلمة مرور السلسلة) إرجاع jsonresult.success () ؛ }/** * استعلام مجموعة متعددة الشرايين * * param username * اسم المستخدم * param rolid * دور المستخدم * param ابدأ * تاريخ البدء * param end * تاريخ الانتهاء * pARAM صفحة * pagination ، بدءًا من 0 * param size * Quorting Quary Quary (Quary) jsonresult query (apiParam (name = "username" ، value = "اسم المستخدم ، الكلمة الرئيسية الاستعلام" ، مطلوب = false) @requestparam (مطلوب = false) اسم المستخدم username ، @apiparam (name = "robeid" ، value = "start". requestparam (مطلوب = خطأ) تاريخ البدء ، apiParam (name = "end" ، value = "رقم دور المستخدم" ، مطلوب = خطأ) @requestparam (مطلوب = خطأ) تاريخ التاريخ ، apiParam (name = "page" ، value = "pagination ، أي صفحة ، بدءًا من 1" ، defaultvalue = "1" ، مطلوب = " apiParam (name = "size" ، value = "عدد الصفوف لكل صفحة ، عدد صحيح موجب" ، defaultValue = "10" ، مطلوب = صواب) @requestparam (defaultValue = "10" ، مطلوب = صواب) int) int). if (null == datas || null == datas.getContent () || datas.getContent (). isempty ()) {رمي bizexception جديد ("المستخدم غير موجود") ؛ } return jsonresult.success (البيانات) ؛ }}عرض مستند واجهة Swagger2
ما سبق هو كل محتوى هذه المقالة. آمل أن يكون ذلك مفيدًا لتعلم الجميع وآمل أن يدعم الجميع wulin.com أكثر.