Bir arayüz tasarlarken dikkate alınması gereken birçok faktör vardır:
Bu makale bu faktörleri kısaca analiz edecektir.
Normatif bir öneri
1. Sorumluluk ilkesi
Bir arayüz tasarlarken, arayüzün sorumluluklarını, yani arayüz türünü, arayüzün çözmesi gereken iş problemini vb. Netleştirmelisiniz.
2. Birlik ilkesi
Açık arayüz sorumlulukları altında, tek bir arayüz elde etmeye çalışın, yani bir arayüz iki veya daha fazla yerine yalnızca bir şey yapar.
Birçok kıdemli olmayan arayüz tasarımcısı, bir arayüz tasarlarken, arayüz ne kadar çok şey yaparsa, o kadar garip olduğunu düşünür.Bu çok ciddi bir yanılgıdır.
3. Protokol belirtimi
Bir arayüz tasarlarken, belirli duruma bağlı olarak arayüz protokolünün HTTP, HTTPS veya FTP olup olmadığını netleştirmek gerekir.
(1) FTP protokolü (Dosya Aktarım Protokolü, kısaca FTP), FTP protokolü kullanılarak .txt, .csv vb. Genel dosya aktarımı gibi dosyaları aktarmak için kullanılan bir dizi standart dosya aktarım protokolüdür
(2) Genelde nispeten düşük güvenlik gereksinimi gerektiren veya hiç güvenlik gerekliliği gerektirmeyen iş senaryoları için geçerli HTTP protokolü
(3) HTTPS = HTTP + SSL, yüksek güvenlik gereksinimleri olan iş senaryoları için uygundur
4. Yol kuralları
API bir kaynak aldığından, URL'de fiiller yerine isimleri kullanmayı deneyin
/api/v1.0/Product/2019
/api/v1.0/Users/2019
5. http istek yöntemi
Arayüzün temel erişim protokolü: al (al), gönder (yeni), koy (değiştir) ve sil (sil)
get / users: Tüm kullanıcıları listeleyin
get / users / id: kullanıcıları kimliğe göre al
post / user: kullanıcı ekle
put / kullanıcı / id: kullanıcıyı kullanıcı kimliğine göre güncelle
sil / kullanıcı / id: kullanıcı kimliğine göre kullanıcıları sil
6. alan adı
Genel olarak, alan adları ana alan adlarına ve tescilli alan adlarına bölünmüştür. Ana alan adı, api'de uzun vadede değişmemiş veya daha az değişiklik olan işletmeler için uygundur. Tescilli alan adı belirli özel hizmetleri çözer.
Örneğin Baidu'yu ele alalım:
(1) Ana alan adı: www.baidu.com
(2) Ürün servisi
Baidu Kütüphanesi: https://wenku.baidu.com/
Baidu biliyor: https://zhidao.baidu.com/
Baidu Bilgileri: https://zhidao.baidu.com/
(3) Pazarlama faaliyetleri
Baidu Hayır Kurumu:
Baidu logosu:
Baidu Dünyası: https://baiduworld.baidu.com
7. Alanlar arası hususlar
Net bir alan adı söz konusu olduğunda, arayüzün alanlar arası olup olmadığını ve alanlar arasında kullanılması gereken teknik araçları vb. Dikkate almalıyız.
8.api sürümü
Arayüzün URL'si için, sürüm numarası eklenmelidir (ör. D, v1.0, v2.0 gibi sürüm numarasını temsil eder)
Örnek: 2019 ürün numarası ve v1.0 sürüm numarası ile ürün bilgilerini alın
/api/v1.0/Pruducts/2019
9. Bilgileri uygun şekilde filtreleyin
Kayıtların sayısı nispeten büyük olduğunda (örneğin, SEÇ * TBName), verileri filtrelemek için TOP, sayfalama, gruplama, sıralama ve WHERE koşulları vb. Gibi bazı koşullar eklenmelidir.
Aşağıda bazı genel parametreler bulunmaktadır.
? limit = 100: 100 veri döndür
? offset = 101: 101. veriden geri dön
? page = 10: 10. sayfaya başvurur
per_page = 100: sayfa başına 100 veri
? sortby = ad: sıralama alanı
? sıra = azalan: azalan sıra
? group = groupName: grup
? producty_type = 1: filtre kriterleri
10. Dönüş veri formatı
Döndürülen veri formatı genellikle üç alan içerir:
(1) Arıza koşulları (durum kodu, hata kodu ve hata açıklaması)
{ "Durum": 0, // durum kodu 0- başarısız anlamına gelir, 1- başarı anlamına gelir "Error_code": "2003", // hata kodu, genellikle tasarım zamanında tanımlanır "Error_des": "Kimlik doğrulama başarısız oldu" // hata açıklaması, genellikle tasarım zamanında tanımlanır }(2) Başarı (kimlik kimliği, veri nesnesi, durum kodu)
{ "Sid": "sh20190111", // jeton kimliği "Kullanıcılar":{ "Kimlik": "al201901111341", // kullanıcı kimliği "Ad": "Alan_beijing", // Kullanıcı Adı "Adr": "kullanıcı adresi" }, "Durum": 1 // durum kodu 0- başarısızlık, 1- başarı anlamına gelir }11. Güvenlik ilkeleri
Arayüz maruziyetinin değerlendirilmesi, arayüz eşzamanlılığının dikkate alınması, arayüz saldırısının önlenmesi, arayüzler arası arayüzün dikkate alınması vb.
12. Ölçeklenebilirlik ilkesi
Arayüzü tasarlarken, arayüzün ölçeklenebilirliğini tamamen göz önünde bulundurun.
13. API sınırlarını tanımlayın
Herhangi bir api, izinler açısından, anonim api ve anonim olmayan api ile ilişkilendirilebilir. Birincisi doğrulama gerektirmez ve ikincisi doğrulama gerektirir.
14. API dönüş kodunu tanımlayın
API'yi tasarlarken, api dönüş kodunu aşağıdaki gibi ayarlamanız gerekir:
Normatif olmayan iki öneri
Bir iş senaryosu vardır: belirli bir arabirimin birden çok api arabirim kombinasyonunun sonucunu döndürmesi gerekir Benzer bir iş senaryosunda, tasarlanan arabirim belirli bir ölçüde standart dışıdır.
1. talep
veri:2. Cevap
{ durum: 0, msg: '', veri: }Üç örnek
Böyle bir iş olduğunu varsayalım: Bir ERP sisteminin iki arayüz sağlaması gerekiyor, biri kullanıcı erişim arayüzü (doğrulama gerekli) ve diğeri kullanıcı kayıt arayüzü (doğrulama gerekli değil).
Bu yazımızın birinci ve ikinci bölümlerindeki tavsiyelere göre iş ihtiyaçlarını karşılayan bir arayüz tasarlayacağız.
(1) Tek tip parametreleri tanımlayın
1. Birleşik giriş parametrelerini tanımlayın
2. Birleşik çıktı parametrelerini tanımlayın
3. Birleştirilmiş bir hata kodu tanımlayın
(2) Arayüz yetkilendirme kategorisini tanımlayın
Aşağıdaki arayüz yetkilendirme kategorisinin tanımıdır
(3) Kullanıcı arayüzü
1. Kullanıcı kaydı
2. Talep
3. Yanıt
4. kod örneği
İstek: { "mobil": 13636595499, "doğrulama kodu": "987654", "pwd": "123456" } Yanıt: (1) hata { "durum": 0, "error_code": 1001, "error_desc": "Mobil doğrulama kodunun süresi doldu" } (2) başarılı { "sid": "sh201901141529", "uid": 1, "durum": 1 }(4) Kullanıcı girişi
1. Oturum açma arayüzüne genel bakış
2. Talep
3. Yanıt
4. Kod
Yanıt: 1. hata { "durum": 0, "error_code": 1002, "error_desc": "Yanlış şifre" } 2. başarılı { "sid": "sh201901141529", "kullanıcı": { "kimlik": 1, "Kullanıcı adı":"", yaş: 0, cinsiyet: 0 }, "durum": 1 }