12 perkara yang perlu diberi perhatian apabila berkongsi dokumen reka bentuk antara muka

Kata Pengantar

Sambil kita membuat pembangunan back-end, kita selalunya perlu mentakrifkan dokumen antara muka.

Baru-baru ini semasa melakukan semakan dokumen antara muka, saya mendapati bahawa parameter yang ditakrifkan oleh rakan kongsi kecil ialah nilai penghitungan, tetapi dokumen antara muka tidak memberikan yang sepadan Nilai penghitungan khusus . Sebenarnya, cara menulis dokumen antara muka dengan baik adalah sangat penting. Hari ini, Saudara Tianluo membawakan anda 12 mata untuk diperhatikan tentang dokumen reka bentuk antara muka~

• Akaun awam : Ambilnya Anak kecil Tian Luo (dengan PDF temu bual asal Tian Luo yang teliti)
• alamat github, terima kasih untuk setiap bintang: github

1 Adakah nama antara muka jelas?

Dengan kata lain, apakah fungsi antara muka anda dan adakah ia mudah difahami dan jelas? Antara muka am url juga memerlukan fungsi antara muka boleh dilihat. Contohnya, Maklumat Pengguna Pertanyaan (QueryUserInfo) ialah nama antara muka yang baik.

2 Adakah alamat antara muka anda lengkap

Alamat antara muka, juga dipanggil URL alamat antara muka. Iaitu, apa yang URL digunakan apabila orang lain memanggil antara muka anda. Contohnya, /api/user/queryUserInfo ialah alamat antara muka . Walau bagaimanapun, apa yang saya ingin katakan ialah ini bukan alamat antara muka yang lengkap. Adakah antara muka anda dipanggil oleh HTTP?

Jika ia dipanggil oleh HTTP, apakah nama domain? Pelabuhan? http alamat antara muka yang baik hendaklah seperti ini:

https//tianluo.com:15000/api/user/queryUserInfo

3. Permintaan antara muka anda Adakah kaedahnya betul?

Kaedah permintaan antara muka biasanya termasuk yang berikut:

• DAPATKAN: Dapatkan sumber daripada pelayan Anda boleh menghantar parameter dalam URL, biasanya digunakan untuk pertanyaan data.
• POST: Serahkan data ke pelayan, biasanya digunakan untuk operasi seperti menambah, mengubah suai, memadam, dsb.
• PUT: Kemas kini sumber ke pelayan, biasanya digunakan untuk mengemas kini data.
• PADAM: Padamkan sumber daripada pelayan, biasanya digunakan untuk memadam data.
• PATCH: Mengemas kini sebahagian sumber kepada pelayan, biasanya digunakan untuk mengubah suai beberapa data.
• HEAD: Sama seperti permintaan GET, tetapi hanya mengembalikan pengepala respons, bukan kandungan entiti Ia biasanya digunakan untuk mendapatkan maklumat meta sumber.
• PILIHAN: Minta pelayan mengembalikan kaedah permintaan yang disokong dan maklumat lain, biasanya digunakan untuk klien dan pelayan merundingkan kaedah permintaan.

Apabila anda mentakrifkan dokumen antara muka, anda perlu menulis dengan jelas, yang manakah kaedah permintaan antara muka anda? Dalam keadaan biasa, kami menggunakan POST和GET lebih kerap. Terdapat juga syarikat yang menggunakan permintaan POST untuk semua antara muka.

4 elemen parameter permintaan

Apabila kami menentukan antara muka, parameter permintaan ialah salah satu bahagian terpenting . Untuk dokumen antara muka yang layak, parameter permintaan hendaklah mengandungi lapan elemen ini:

• Nama parameter: Nama parameter dinamakan dalam kes unta, seperti userId. Jenis
• : Jenis parameter, seperti String、Integer, dsb.
• Sama ada ia diperlukan: Sama ada parameter permintaan diperlukan Jika ia diperlukan, apabila huluan tidak melepasi parameter ini, pengecualian pengesahan parameter harus dibuang.
• Nilai lalai: Jika parameter ini tidak diluluskan, adakah terdapat nilai lalai dan apakah nilai lalai.
• julat nilai: Jika ia adalah jenis berangka seperti Long，Integer, ini ialah nilai julat, seperti 1~10 Jika ia adalah nilai penghitungan, ia ialah julat penghitungan, seperti ACTIVE、INACTIVE.
• Format parameter: Contohnya, jika parameter anda ialah tarikh, anda perlu menentukan format parameter, seperti yyyyMMdd
• Nilai contoh parameter input: Berikan contoh nilai respons parameter supaya pembangun dapat Memahami dan menggunakan parameter ini dengan lebih baik.
• Nota: Jika medan parameter input ini mempunyai arahan khas, anda boleh menerangkannya dalam lajur ini. Jika tiada penjelasan khas, tidak mengapa untuk menerangkan fungsi parameter ini sahaja.

Berikut ialah contoh dokumen :

5 7 keperluan utama untuk parameter respons

Parameter respons sebenarnya serupa dengan parameter input, dengan 7 elemen:

Nama parameter: Nama yang menerangkan parameter tindak balas.
• Jenis parameter: menerangkan jenis data parameter respons, seperti
• , dsb. String、Integer
Format parameter: menerangkan format data parameter respons, seperti
• , dsb. yyyy-MM-dd、HH:mm:ss
Perihalan parameter: Penerangan terperinci tentang maksud parameter tindak balas.
• Julat nilai: Menghuraikan julat nilai parameter tindak balas, seperti
• julat integer, panjang rentetan, dsb.
Diperlukan atau tidak: Terangkan sama ada parameter tindak balas diperlukan.
• Nilai contoh: Berikan nilai contoh untuk parameter respons ini supaya pembangun dapat memahami dan menggunakan parameter ini dengan lebih baik. Perbezaan antara

: code，msg，data

{
    "code": 0,
    "message": "success",
    "data": {
        "name": "Tom",
        "age": 20,
        "gender": "男"
    }
}

kod ralat, maklumat kod ralat, makna

7.接口安全

定义接口文档时，对于一些需要保护的接口，也需要考虑接口的安全，例如权限管理、防止 SQL 注入等。

因此，接口文档应当包含接口的安全性说明：例如接口的访问授权方式、数据传输加密方式等。此外，接口文档还应该对于敏感数据和操作进行标注，方便使用者注意隐私和安全问题。

8. 接口版本管理

在接口文档定义时，接口版本管理是非常重要的一个方面。由于软件项目的迭代和升级，接口可能会随着版本的变化而发生变化。为了避免接口变化给用户带来不必要的困扰，需要对接口进行版本管理。

以下是一些常用的接口版本管理方法：

• 在接口文档中明确版本号：在接口文档中明确标识接口的版本号，例如在接口地址中添加版本号信息，如https://example.com/api/v1/user，表示该接口的版本号为v1。
• 使用语义化版本号：采用语义化版本号（Semantic Versioning）规范，即版本号格式为X.Y.Z，其中X表示主版本号、Y表示次版本号、Z表示修订号。当进行兼容性变更时，需升级主版本号；当增加功能且不影响现有功能时，需升级次版本号；当进行bug修复或小功能改进时，需升级修订号。
• 增量发布：在接口发生变化时，先发布新版本的接口，同时保留旧版本的接口。用户可以根据自己的需求来选择使用哪个版本的接口。随着新版本的接口逐步替换旧版本的接口，最终可以将旧版本的接口废弃。

无论采用何种方法，接口版本管理都应该得到充分的考虑。在接口版本变化时，需要及时更新接口文档（详细描述版本的变化、兼容性问题、版本切换方式等），以确保用户能够获得最新的接口信息。

9. 维护接口文档更新迭代

如果接口发生了变更，比如参数有哪些变更，错误码变更等等，都需要维护到文档上。同时需要登记变更的记录。

10.明确请求头有哪些

接口文档，是需要写清楚的请求头的。接口文档的请求头可以看到以下的信息：

• Content-Type：指定请求体的数据格式，如application/json、application/x-www-form-urlencoded、multipart/form-data等。
• Authorization：用于身份验证的令牌信息，如Token、Bearer等。
• Accept：指定客户端可以接受的响应数据格式，如application/json、text/html等。
• User-Agent：指定客户端的类型和版本信息，可以用于服务端进行针对性优化。
• Accept-Encoding：指定客户端可以接受的数据压缩格式，如gzip、deflate等。
• Cache-Control：指定客户端缓存的策略，如no-cache、max-age等。
• Cookie：包含客户端发送给服务器的cookie信息。

这是是一个接口文档的请求头的示例：

POST /api/user HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Accept: application/json
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/96.0.4664.110 Safari/537.36
Accept-Encoding: gzip, deflate, br
Cache-Control: no-cache
Cookie: _ga=GA1.2.1234567890.1234567890; _gid=GA1.2.0987654321.0987654321
If-None-Match: W/"2a-3TjT7VaqgkT1nJdKjX9Cpijp2FA"
Referer: https://example.com/login
Origin: https://example.com
Content-Length: 43

{"name": "John Doe", "age": 25, "email": "john.doe@example.com"}

11 接口请求示例

接口文档，需要提供接口的使用案例：以方便开发者理解接口的使用方法和调用流程。

12. 接口测试

一般来说，接口文档需要完善：接口测试的方法和测试结果，以便用户可以测试接口是否符合自己的需求，让用户用得放心~哈哈