คำเตือน : แม้ว่าฉันจะอยู่ในรายการสิ่งที่ทำให้ชีวิตของฉันยากขึ้นเมื่อใช้แพลตฟอร์ม API แต่ฉันก็ยังคิดว่ามันเป็นทางออกที่ดีในการสร้างต้นแบบ crud ที่รวดเร็ว บทความนี้ส่งถึงผู้ที่ต้องการสร้างโซลูชันที่ใช้ API ในระยะยาว

โดยหลักการแล้วมี FOSRestBundle กล่องวิเศษเล็ก ๆ ที่เป็นประกายเพื่อสร้างสิ่งที่คล้ายกับ REST API ที่จริงมันมีเวทมนตร์มากเกินไป ..

จากนั้นแพลตฟอร์ม API ก็มาและปวดหัวกับมัน

แม้จะมีเอกสารระบุว่า“ ทุกอย่างสามารถปรับแต่งได้อย่างสมบูรณ์ผ่านระบบเหตุการณ์ที่มีประสิทธิภาพและ OOP ที่แข็งแกร่ง” ความจริงก็คือแทบจะเป็นไปไม่ได้ที่จะปรับแต่งพฤติกรรมและตรรกะที่ลึกซึ้งภายในส่วนประกอบของ API และตัวเลือกที่จะจับคู่กับ Symfony Serializer ตัวเลือกการกำหนดค่าที่มีประสิทธิภาพน้อยลงและไม่ดีเท่าที่ฉันเคยเห็นมา) ยิ่งทำให้แย่ลง แต่นี่คือสิ่งที่ฉันค้นพบในตอนท้ายของการเดินทางสู่แพลตฟอร์ม API อันเหลือเชื่อนี้ ..

การเดินทางเริ่มต้นขึ้น

สิ่งแรกที่ฉันสังเกตเห็นเมื่อฉันเริ่มใช้ API Platform คือไม่รองรับการกำหนดเวอร์ชัน คุณสามารถใส่คำนำหน้าในเส้นทางของคุณและแสร้งทำเป็นว่าเป็นระบบกำหนดเวอร์ชัน แต่ความจริงก็คือเครื่องมือไม่ได้ช่วยคุณเลย ในที่สุดฉันก็ไม่ชอบเวอร์ชันในพา ธ : มันไม่ได้เป็นแบบ RESTy ฉันอยากจะส่งผ่านส่วนหัวของคำขอ (อันที่กำหนดเองหรือแอตทริบิวต์ของส่วนหัวที่ยอมรับ)

ดังนั้นฉันจึงเริ่มสำรวจบริการ, normalizers, คลาสสุดท้ายที่มีการอ้างอิงที่จำเป็นสิบสอง (!) และการอ้างอิงที่เป็นทางเลือกสี่แบบเพื่อค้นพบว่าทุกอย่างในแพลตฟอร์ม API หมุนรอบข้อกำหนด OpenAPI

OpenAPI โอ้!

ฉันถือว่า OpenAPI เป็นตัวอย่างที่ดีในการไม่เขียนข้อกำหนด ส่วนหนึ่งเป็นเพราะมันพยายามที่จะได้รับโปรโตคอลจากมาตรฐานสถาปัตยกรรม (ซึ่ง REST คือ) และนี่เป็นงานที่แทบจะเป็นไปไม่ได้เลย และส่วนหนึ่งเป็นเพราะข้อ จำกัด ของโปรโตคอลที่ออกแบบมาอย่างดีเช่น HTTP

ตัวอย่างเช่น OpenAPI จำกัด เมธอด HTTP ที่คุณสามารถใช้ได้กับวิธีมาตรฐาน (ไม่ใช่วิธีมาตรฐานทั้งหมดแต่นี่เป็นอีกเรื่องหนึ่ง) แม้ว่าข้อกำหนด HTTP จะระบุอย่างชัดเจนว่าเมธอดนั้นเป็นเพียงกลุ่มของอักขระ US-ASCII มันไม่ได้กำหนดแม้กระทั่งการลงทะเบียนวิธีการที่ไม่ได้มาตรฐานให้กับ IANA ดังนั้นทำไมข้อกำหนดที่ใช้ในการกำหนดวิธีการเขียนโปรโตคอล API ของคุณจึงควร จำกัด

อย่างไรก็ตามความพยายามที่ไม่ธรรมดาในการสร้างสคีมา OpenAPI นำไปสู่ความเป็นไปไม่ได้ที่จะมี API เวอร์ชันสำหรับของจริง เมื่อฉันรู้เช่นนั้นความคิดของฉันก็ระเบิดขึ้น

หลังจากลบล้างบางอย่างเช่น 14 บริการเพียงเพื่อแก้ไขการโทรครั้งเดียวที่มีอยู่ในคลาสสุดท้ายซึ่งจำเป็นตลอดทั้ง API Platform codebase โดยไม่ระบุอินเทอร์เฟซฉันเริ่มสงสัย ..

การเดินทางยังคงดำเนินต่อไป: DTOs, Serializer และการตรวจสอบความถูกต้อง

สิ่งที่สำคัญที่สุดอย่างหนึ่งที่ฉันได้เรียนรู้จากการทำงานในโครงการเสาหินคือการใช้ DTO และเอนทิตีแบบจำลองที่สมบูรณ์ พวกเขาอนุญาตให้ฉันหลีกเลี่ยงข้อผิดพลาดในฐานข้อมูลลดความซับซ้อนของลอจิกของรูปแบบไดนามิกและเริ่มเป็นจอกศักดิ์สิทธิ์ของโครงการของฉัน: มันสะดวกเกินไปที่จะใช้

ฉันคิดว่า DTO อาจช่วยฉันแก้ปัญหานี้ได้เช่นกัน ฉันผิดไป.

แพลตฟอร์ม API รองรับ DTO แต่ไม่ค่อยดีนัก (พูดตามตรงเพื่อนร่วมงานคนหนึ่งของฉันบอกฉันว่าตอนนี้การสนับสนุน DTO ดีขึ้น แต่เมื่อฉันลองแล้วมันแย่มาก) ไม่มีเอกสารมากนักดังนั้นฉันจึงต้องพยายามใช้มันโดยตรงกับรหัส

ลองครั้งแรก: เขียน DTO แบบธรรมดาประกาศในอินพุตและเอาต์พุตของคำอธิบายประกอบ ApiResource เพิ่มคำอธิบายประกอบการตรวจสอบความถูกต้องของคุณสมบัติ DTO เขียนหม้อแปลงส่งข้อมูลที่ถูกต้องทุกอย่างเรียบร้อย จากนั้นฉันพยายามส่งผ่านข้อมูลที่ไม่ถูกต้อง: 500

อืม .. ฉันเปิดโปรไฟล์ของเว็บไปที่ส่วนการตรวจสอบความถูกต้องและ…แปลกใจ! แพลตฟอร์ม API เรียกว่าการตรวจสอบความถูกต้องในเอนทิตี WTF?!

แนวทางดังกล่าวไม่ดีด้วยเหตุผลหลายประการ แต่เห็นได้ชัดว่าไม่เข้ากันกับเอนทิตีแบบจำลองที่สมบูรณ์เนื่องจากข้อมูลที่ไม่ถูกต้องจะทำให้เกิดข้อยกเว้นเมื่อพยายามตั้งค่าเป็นเอนทิตี นอกจากนี้หากฟิลด์ไม่ถูกต้องในเอนทิตี แต่ไม่มีอยู่ใน DTO (หรือมีชื่อแทน) ข้อผิดพลาดกับฟิลด์ที่ไม่รู้จักจะถูกส่งกลับไปยังไคลเอนต์ ไม่มีทาง!
แก้ไข:มีคนบอกฉันว่าพฤติกรรมนี้ได้รับการแก้ไขแล้ว แต่มีอยู่ในเวลานั้นและอย่างไรก็ตามการสนับสนุน DTO ยังคงมีอยู่อย่าง จำกัด

สิ่งที่ทำให้แย่ลงคือการใช้ Symfony Serializer ซึ่งไม่สามารถแทนที่ได้ ความขาดแคลนของตัวเลือกการกำหนดค่า (ในขณะที่ไม่มีฟังก์ชันพื้นฐานเช่นแอตทริบิวต์ละเว้น) และการขาดการควบคุมเกี่ยวกับแอตทริบิวต์ที่จะเปิดเผยและการสร้างวัตถุทำให้น่าหงุดหงิด
นอกจากนี้การใช้ deserialisers ซึ่งอาจทำให้เกิดข้อยกเว้นสำหรับข้อมูลที่ไม่ถูกต้องทำให้ทุกอย่างไม่เสถียรและไม่น่าเชื่อถือเนื่องจากข้อผิดพลาดเหล่านั้นจะถูกส่งกลับไปยังไคลเอนต์ด้วยวิธีที่แตกต่างไปจากข้อผิดพลาดในการตรวจสอบความถูกต้อง

แพลตฟอร์มปวดหัว: จุดสิ้นสุดของการเดินทาง

สิ่งที่ทำให้ทุกอย่างซับซ้อนขึ้นเรื่อย ๆ คือการใช้ไฮดราและ jsonld อย่างเข้มข้น เป้าหมายของ API Platform คือเป็นเพียง API เดียวที่มีอยู่ในระบบ แต่ในโลกแห่งความเป็นจริงคุณอาจกำลังทำงานกับ API หนึ่งที่เปิดเผยโดยบริการหนึ่งที่พัฒนาควบคู่ไปกับบริการอื่น ๆ และ API อื่น ๆ API เหล่านี้อาจสื่อสารกันและเปิดเผยข้อมูลอ้างอิงและข้อมูลจากต่างประเทศ

การจัดทำเอกสารเพียงฉบับเดียวสำหรับสถาปัตยกรรมทั้งหมดไม่สามารถทำได้จากหนึ่งในบริการเหล่านี้เนื่องจากไม่สามารถทราบสถาปัตยกรรมของบริการอื่นได้

ฟังก์ชันนอกขอบเขต (การพิสูจน์ตัวตน JWT ตัวสร้างผู้ดูแลระบบ ฯลฯ ) ตัวกรองที่ออกแบบมาไม่ดี (ไม่สามารถใช้นามแฝงได้เช่น) การแบ่งหน้าด้วยเพจ (ซึ่งเป็นแนวคิดส่วนหน้า) และการสนับสนุนที่ จำกัด สำหรับคำขอ PATCH ทำให้ฉันได้รับการยืนยันเท่านั้น ข้อสงสัยของฉัน:

แพลตฟอร์ม API ยังไม่พร้อมและไม่ได้ออกแบบมาให้เป็นเครื่องมือ API ที่เชื่อถือได้ในโลกของไมโครเซอร์วิส

แล้วไงล่ะ?

ผมจึงเริ่มจากศูนย์ เริ่มโครงการ Symfony ใหม่เริ่มเขียนสิ่งต่างๆเพื่อให้มีระบบการกำหนดเวอร์ชันที่มีประสิทธิภาพเพื่อให้เข้ากันได้กับเอนทิตีแบบจำลองที่สมบูรณ์โดยไม่มีข้อ จำกัด ของ OpenAPI และด้วย DTO เพื่อเป็นจุดศูนย์กลางของสถาปัตยกรรม API

ตอนนี้ฉันตัดสินใจที่จะเปิดรหัสของฉันและเผยแพร่บน GitHub ฉันต้องการให้โครงการนี้เป็นกล่องเครื่องมือที่มั่นคงในการเขียน REST API ซึ่งสามารถบำรุงรักษาได้ในโครงการระยะยาวโดยเรียนรู้จากทุกสิ่งที่ฉันไม่ชอบในชุดเครื่องมือ API อื่น ๆ

ฉันเรียกมันว่า Solido และนี่คือเอกสาร: https://solid-o.github.io/docs/

เห็นได้ชัดว่าอยู่ภายใต้การพัฒนาอย่างแข็งขันและฉันกำลังมองหาผู้อื่นที่จะมาร่วมสร้างกล่องเครื่องมือ API โอเพนซอร์สที่แข็งแกร่งเขียนดีและมีประโยชน์

ขอบคุณที่อ่าน
อ.