Artikel ini memperkenalkan praktik terbaik untuk Spring Boot untuk mengembangkan antarmuka REST dan membagikannya kepada Anda, sebagai berikut:
Kata kerja http sesuai dengan perintah sql
MENDAPATKAN
Dapatkan sumber daya dari server, Anda dapat memperoleh satu atau lebih sumber daya, dan mendapatkan semua informasi pengguna di server, mendapatkan /pengguna /ID, ID yang ditentukan, dan mendapatkan informasi pengguna dari ID yang ditentukan.
POS
Buat sumber daya baru di server, sesuai dengan createPost /pengguna di perintah SQL untuk membuat pengguna baru
MELETAKKAN
Perbarui sumber daya di server, dan klien menyediakan sumber daya lengkap yang diubah, sesuai dengan updatePut /pengguna /ID di perintah SQL untuk memperbarui semua informasi pengguna dengan ID yang ditentukan
MENGHAPUS
Hapus sumber daya dari server, dan hapus informasi pengguna dari ID yang ditentukan yang sesuai dengan DeletEdeLete /Users /ID dalam perintah SQL
Tambalan
Perbarui beberapa atribut sumber daya di server, sesuai dengan UpdatePatch /Users /ID di perintah SQL untuk memperbarui atribut tertentu dari pengguna dengan ID yang ditentukan
Konvensi dalam URL
Kata benda dalam URL menggunakan bentuk jamak
Pertanyaan apakah nama dalam URL menggunakan tunggal atau jamak telah kontroversial. Kata benda dalam URL umumnya sesuai dengan tabel dalam database, dan tabel menyimpan data yang sama. Dalam praktiknya, saya memaksakan penggunaan bentuk jamak, yang terlihat lebih nyaman.
/pengguna/pengguna/1/peran/peran/peran/1
Adapun beberapa kata benda yang tidak teratur dan tak terhitung, itu tergantung pada pendapat Anda.
/pahlawan/pahlawan/1/orang/orang/1/kaki/kaki/1/kaki/kaki/1/kaki/kaki/1
Versi
Bicara nomor versi yang akan ditambahkan ke URL untuk menangani perubahan yang tidak kompatibel dan destruktif. Saat merilis API baru, klien dapat pindah ke API baru secara bebas dan tidak akan dalam masalah karena memanggil API baru yang sama sekali berbeda. Gunakan awalan "V" intuitif untuk menunjukkan bahwa nomor berikut adalah nomor versi, tidak ada nomor versi sekunder yang diperlukan, dan versi API tidak boleh sering dirilis.
/edu/v1/user/edu/v1/peran
Gunakan string kueri untuk parameter opsional dan kompleks
Untuk membuat URL lebih kecil dan lebih ringkas, atur URL dasar untuk sumber daya, dan parameter opsional dan kompleks diwakili oleh string kueri.
/edu/v1/pengguna? Diaktifkan = 1 & roleId = 1
Memberikan informasi paging
Bukan ide yang baik untuk mengembalikan semua sumber daya dalam database sekaligus, jadi diperlukan mekanisme paging. Biasanya, parameter terkenal dalam database digunakan untuk mengimbangi dan membatasi
/edu/v1/pengguna? Diaktifkan = 1 & offset = 1 & batas = 15
Jika klien tidak melewati parameter ini, nilai default harus digunakan, biasanya offset = 0, batas = 10.
Gunakan kata kerja untuk permintaan non-sumber daya
Terkadang panggilan API tidak melibatkan sumber daya, dalam hal ini server melakukan operasi dan mengembalikan hasilnya ke klien.
/edu/v1/calc? p = 100
Pertimbangkan sumber daya spesifik dan pencarian lintas sumber daya
Sangat mudah untuk memberikan pencarian untuk akhir-waktu tertentu. Anda hanya perlu menggunakan pengumpulan sumber daya yang sesuai dan menambahkan string pencarian ke parameter kueri.
/EDU/V1/Pengguna? Nama pengguna = Li Qinghai
Jika Anda perlu memberikan pencarian global untuk semua sumber daya, Anda perlu menggunakan metode lain.
/edu/v1/pencarian? key = li qinghai
Hasil respons
Gunakan nomenklatur unta kecil sebagai pengidentifikasi atribut
Biasanya, layanan web yang tenang akan digunakan oleh klien yang ditulis dalam JavaScript. Klien mengubah respons JSON ke objek JavaScript dan kemudian memanggil propertinya. Oleh karena itu, yang terbaik adalah mengikuti spesifikasi umum kode JavaScript.
person.year_of_birth // tidak disarankan, melanggar kode spesifikasi umum JavaScript.
Memberikan informasi paging
Ketika ada banyak hasil yang dikembalikan, informasi paging harus disediakan.
{"halaman": 0, "size": 10, "total": 3465, "obj": []}Antarmuka Istirahat Pengembangan MVC Musim Semi
Anotasi Umum
@RestController
@RestController adalah anotasi kombinasi dari @ResponseBody dan @Controller.
@Requestmapping
Anotasi ini dapat diterapkan pada metode pengontrol atau ke kelas pengontrol ini. Ketika pengontrol menambahkan anotasi @RequestMapping di tingkat kelas, anotasi ini diterapkan pada semua metode prosesor pengontrol. Anotasi @RequestMapping pada metode prosesor akan melengkapi deklarasi @Requestmapping di tingkat kelas.
@Postmapping
Anotasi kombinasi adalah singkatan dari @RequestMapping (Method = RequestMethod.post).
@PutMapping
Anotasi kombinasi adalah singkatan dari @RequestMapping (Method = requestMethod.put).
@Patchmapping
Anotasi kombinasi adalah singkatan dari @RequestMapping (Method = RequestMethod.patch).
@Deletemapping
Anotasi kombinasi adalah singkatan dari @RequestMapping (Method = requestMethod.delete).
@Getmapping
Anotasi kombinasi adalah singkatan dari @RequestMapping (Method = requestMethod.get).
@PathVariable
Dapatkan data di URL.
@RequestParam
Mendapatkan nilai parameter yang diminta.
Contoh Dokumentasi Antarmuka dan API Swagger
Untuk penggunaan Swagger, silakan merujuk pada penggunaan Swagger2 di Proyek Spring Boot. Kode dalam Badan Metode tidak penting, yang penting adalah tanda tangan metode dan pemetaan dengan kata kerja HTTP.
Impor java.util.date; impor javax.persistence.entitynotfoundException; impor org.springframework.beans.factory.annotation.Autowired; impor org.springframework.data.domain.page; impor org.springframework.bind.bind.bindeB.bind.anning; org.springframework.web.bind.annotation.patchmapping; impor org.springframework.web.bind.annotation.pathvariable; impor org.springframework.web.bind.annotation.postmapping; impor org.springframework.nbind.nnind.annotation org.springframework.web.bind.annotation.requestmapping; impor org.springframework.web.bind.annotation.requestparam; impor org.springframework.web.bind.annotation.restcontroller; impor cn.com.infcn.jianshiceShice. cn.com.infcn.jianshu.exception.bizexception; import cn.com.infcn.jianshu.exception.loginnameorpassworderRorexception; impor cn.com.infcn.jianshu.exception.resourceExistsException; impor; cn.com.infcn.jianshu.util.JsonResult;import io.swagger.annotations.Api;import io.swagger.annotations.ApiParam;/** * System User Controller * * @author Li Qinghai* */@Api(value = "System User Interface", tags = "System Manajemen ")@restcontroller@requestMapping ("/v3/edu/users ") kelas publik usercontroller {@autowired private userservice userService; /** * Tambahkan Pengguna, Daftarkan * * @param LoginName * Akun Login * @param Nama pengguna * Nama pengguna * @param Kata sandi * Kata sandi login * @param roleId * Peran pengguna * @return * @throws ResourceExistSException */@apioperation (value = "add User") @postmapping ("/") public joninn (value = "add User") @postmapping ("/") public joninn (value = "nilai =" @postmapping ("/") public jonong (value = "nilai") account", required = true) @RequestParam(required = true) @RequestBody String loginName, @ApiParam(name = "userName", value = "Username", required = true) @RequestParam(required = true) @RequestBody String userName, @ApiParam(name = "password", value = "Log in password", required = true) @RequestParam(required = true) @RequestBody String Kata sandi, @Apiparam (name = "roleId", value = "nomor peran pengguna", wajib = true) @RequestParam (wajib = true) @RequestBody String roleID) melempar ResourceExistSException {boolean exist = this.userservice.exists (loginName); if (ada) {lempar sumber daya baru existsException (loginName); } User user = userservice.create (loginName, kata sandi, nama pengguna, roleID); return jsonresult.success (pengguna); }/** * Login pengguna dengan akun login dan kata sandi login * * @param LoginName * Akun login * @param Kata Sandi * Kata sandi login * @Throws EntityNotFoundException */@Apioperation (value = "Informasi Pengguna @pexiPer = @pexiPing ("/Login ") LOGINOM PUBLIC (NOVITEP (" true) @RequestParam (wajib = true) string LoginName, @apiparam (name = "password", value = "Login Password", wajib = true) @RequestParam (wajib = true) kata sandi string) melempar loginNameorPassWorderRorexception {user user = this.userservice.login (loginname, loginname, loginname, login); if (null == user) {throw new LoginNameOrPassWorderRorexception (); } return jsonResult.success (pengguna); } /** * Query user information based on user number* * @param id * User number* @throws EntityNotFoundException */ @ApiOperation(value = "Query user information based on user number") @GetMapping("/{id}") public JsonResult read( @ApiParam(name = "id", value = "User number, primary key", required = true) @PathVariable(required = true) String id) melempar EntityNotFoundException {user user = this.userservice.getone (id); return jsonresult.success (pengguna); }/** * Akun dibatalkan, dan data pengguna tidak dihapus * * @param userid * nomor pengguna * @return */@apioperation (value = "carded out of account") @patchmapping ("/{id}") public jsonResult batal (@apiparam (name = "id", value = "value =" noumber = User = @apiparam (name = "id", value = "value = user noumber = PRIMER PUBLY (NAME (name =" id ", value =" NOUMES PENGGUNA) PUBER EntityNotFoundException {this.userservice.cancel (id); return jsonResult.success (); } /** * Reset password* * @param id * User number* @param password * New login password* @return */ @ApiOperation(value = "Reset password") @PatchMapping("/") public JsonResult updatePassword( @ApiParam(name = "id", value = "User number, primary key", required = true) @RequestParam(required = true) String id, @ApiParam(name = "Kata sandi", value = "Kata Sandi Login Baru", Diperlukan = Benar) @RequestParam (Diperlukan = Benar) Kata sandi string) {this.userservice.updatePassword (id, kata sandi); return jsonResult.success (); } / ** * Permintaan kombinasi multi-kondisi * * @param nama pengguna * Nama pengguna * @param roleId * Peran pengguna * @param mulai * Tanggal mulai * @param akhir * Tanggal akhir * @param halaman * pagination, mulai dari 0 * @param ukuran * Jumlah baris per halaman, default 10 * @return * @throws BizException * @GetMapping("/") public JsonResult query( @ApiParam(name = "userName", value = "User name, query keyword", required = false) @RequestParam(required = false) String userName, @ApiParam(name = "roleId", value = "User Role Number", required = false) @RequestParam(required = false) String roleId, @ApiParam(name = "start", value = "User Role Number", required = false) @RequestParam(required = false) Date start, @ApiParam(name = "end", value = "User Role Number", required = false) @RequestParam(required = false) Date end, @ApiParam(name = "page", value = "Pagination, which page, starting from 1", defaultValue = "1", required = true) @RequestParam(defaultValue = "1", wajib = true) int Page, @apiparam (name = "size", value = "Jumlah baris per halaman, bilangan bulat positif", defaultValue = "10", wajib = true) @RequestParam (DefaultValue = "10", wajib = true) Int ukuran) BizeSception {Page <user>, start, ini, Page, starer, starer. halaman, ukuran); if (null == data || null == datas.getContent () || datas.getContent (). isEmpty ()) {throw new BizException ("pengguna tidak ada"); } return jsonResult.success (data); }}Rendering Dokumen Antarmuka Swagger2
Di atas adalah semua konten artikel ini. Saya berharap ini akan membantu untuk pembelajaran semua orang dan saya harap semua orang akan lebih mendukung wulin.com.