การใช้เครื่องมือตรวจสอบโค้ด เช่น lint จะช่วยให้คุณค้นพบปัญหาและปรับปรุงโค้ดได้ แต่เครื่องมือตรวจสอบจะอนุมานได้เพียงบางส่วนเท่านั้น ตัวอย่างเช่น รหัสทรัพยากร Android จะใช้ int เพื่อระบุสตริง กราฟิก สี และทรัพยากรประเภทอื่นๆ ดังนั้นเครื่องมือตรวจสอบจึงไม่สามารถบอกได้เมื่อคุณระบุทรัพยากรสตริงในตำแหน่งที่ควรระบุสี สถานการณ์นี้หมายความว่าแอปอาจแสดงผลไม่ถูกต้องหรือทำงานไม่ได้เลย แม้ว่าคุณจะใช้การตรวจสอบโค้ดก็ตาม
คำอธิบายประกอบช่วยให้คุณระบุคำแนะนำแก่เครื่องมือตรวจสอบโค้ด เช่น Lint เพื่อช่วยตรวจหาปัญหาโค้ดที่ละเอียดอ่อนมากขึ้นเหล่านี้ได้ ระบบจะเพิ่มคำอธิบายประกอบเป็นแท็กข้อมูลเมตาที่คุณแนบกับตัวแปร พารามิเตอร์ และค่าที่แสดงผลเพื่อตรวจสอบค่าที่แสดงผลของเมธอด พารามิเตอร์ที่ส่ง ตัวแปรในเครื่อง และฟิลด์ เมื่อใช้กับเครื่องมือตรวจสอบโค้ด คำอธิบายประกอบจะช่วยให้คุณตรวจพบปัญหาต่างๆ เช่น null pointer exception และความขัดแย้งของประเภททรัพยากร
Android รองรับคำอธิบายประกอบที่หลากหลายผ่านไลบรารีคำอธิบายประกอบ Jetpack
คุณเข้าถึงไลบรารีได้ผ่านแพ็กเกจ
androidx.annotation
หมายเหตุ: หากโมดูลมีทรัพยากร Dependency ในโปรเซสเซอร์สำหรับคำอธิบายประกอบ คุณต้องใช้การกำหนดค่าทรัพยากร Dependency kapt หรือ ksp สำหรับ Kotlin หรือการกำหนดค่าทรัพยากร Dependency annotationProcessor สำหรับ Java เพื่อเพิ่มทรัพยากร Dependency นั้น
เพิ่มคำอธิบายประกอบลงในโปรเจ็กต์
หากต้องการเปิดใช้คำอธิบายประกอบในโปรเจ็กต์ ให้เพิ่มทรัพยากร Dependency androidx.annotation:annotation ลงในไลบรารีหรือแอป ระบบจะตรวจสอบคำอธิบายประกอบที่คุณเพิ่มเมื่อคุณเรียกใช้การตรวจสอบโค้ดหรืองาน lint
เพิ่มทรัพยากร Dependency ของไลบรารี Jetpack Annotations
ไลบรารีคำอธิบายประกอบ Jetpack เผยแพร่อยู่ในที่เก็บ Maven ของ Google
หากต้องการเพิ่มไลบรารี Jetpack Annotations ลงในโปรเจ็กต์ ให้ใส่บรรทัดต่อไปนี้ในบล็อก dependencies ของไฟล์ build.gradle หรือ build.gradle.kts
Kotlin
dependencies { implementation("androidx.annotation:annotation:1.11.0") }
ดึงดูด
dependencies { implementation 'androidx.annotation:annotation:1.11.0' }
หากคุณใช้คำอธิบายประกอบในโมดูลไลบรารีของคุณเอง ระบบจะรวมคำอธิบายประกอบไว้เป็นส่วนหนึ่งของอาร์ติแฟกต์ Android Archive (AAR) ในรูปแบบ XML ในไฟล์ annotations.zip การเพิ่มทรัพยากร Dependency androidx.annotation จะไม่ทำให้เกิดทรัพยากร Dependency สำหรับผู้ใช้ปลายทางของไลบรารี
หมายเหตุ: หากใช้ไลบรารี Jetpack อื่นๆ คุณอาจไม่จำเป็นต้องเพิ่มทรัพยากร Dependency androidx.annotation เนื่องจากไลบรารี Jetpack อื่นๆ จำนวนมากขึ้นอยู่กับไลบรารีคำอธิบายประกอบ คุณจึงอาจมีสิทธิ์เข้าถึงคำอธิบายประกอบอยู่แล้ว
ดูรายการคำอธิบายประกอบทั้งหมดที่รวมอยู่ในที่เก็บ Jetpack ได้ที่ข้อมูลอ้างอิงไลบรารีคำอธิบายประกอบ Jetpack หรือใช้ฟีเจอร์เติมข้อความอัตโนมัติเพื่อแสดงตัวเลือกที่ใช้ได้สำหรับคำสั่ง import androidx.annotation.
เรียกใช้การตรวจสอบโค้ด
หากต้องการเริ่มการตรวจสอบโค้ดจาก Android Studio ซึ่งรวมถึงการตรวจสอบความถูกต้องของคำอธิบายประกอบและการตรวจสอบ Lint อัตโนมัติ ให้เลือกวิเคราะห์ > ตรวจสอบโค้ดจากเมนู Android Studio จะแสดงข้อความความขัดแย้งเพื่อแจ้งปัญหาที่อาจเกิดขึ้นซึ่งโค้ดของคุณขัดแย้งกับคำอธิบายประกอบ และแนะนำวิธีแก้ปัญหาที่เป็นไปได้
นอกจากนี้ คุณยังบังคับใช้คำอธิบายประกอบได้โดยเรียกใช้งาน lint โดยใช้บรรทัดคำสั่ง แม้ว่าวิธีนี้อาจเป็นประโยชน์ในการแจ้งปัญหาเกี่ยวกับเซิร์ฟเวอร์การรวมอย่างต่อเนื่อง แต่งาน lint จะไม่บังคับใช้คำอธิบายประกอบ Nullness (อธิบายไว้ในส่วนถัดไป) มีเพียง Android Studio เท่านั้นที่ทำเช่นนี้ ดูข้อมูลเพิ่มเติมเกี่ยวกับการเปิดใช้และการตรวจสอบ Lint ได้ที่การปรับปรุงโค้ดด้วยการตรวจสอบ Lint
แม้ว่าความขัดแย้งของคำอธิบายประกอบจะสร้างคำเตือน แต่คำเตือนเหล่านี้จะไม่ทำให้แอปของคุณคอมไพล์ไม่ได้
คำอธิบายประกอบ Nullness
คำอธิบายประกอบ Nullness มีประโยชน์ในโค้ด Java เพื่อบังคับใช้ว่าค่าเป็น Null ได้หรือไม่ ซึ่งมีประโยชน์น้อยกว่าในโค้ด Kotlin เนื่องจาก Kotlin มีกฎความสามารถในการเว้นว่างในตัวที่บังคับใช้ในเวลาคอมไพล์เพิ่มคำอธิบายประกอบ @Nullable และ @NonNull เพื่อตรวจสอบค่า Null ของตัวแปร พารามิเตอร์ หรือค่าที่แสดงผลที่ระบุ คำอธิบายประกอบ @Nullable บ่งชี้ถึงตัวแปร พารามิเตอร์ หรือค่าที่แสดงผลซึ่งอาจเป็น Null ได้
@NonNull บ่งบอกถึงตัวแปร พารามิเตอร์ หรือค่าที่แสดงผลซึ่งเป็นค่า Null ไม่ได้
เช่น หากมีการส่งตัวแปรภายในที่มีค่า Null เป็นพารามิเตอร์ไปยังเมธอดที่มีคำอธิบายประกอบ @NonNull แนบอยู่กับพารามิเตอร์นั้น การสร้างโค้ดจะสร้างคำเตือนที่ระบุถึงความขัดแย้งที่ไม่ใช่ Null นอกจากนี้ การพยายามอ้างอิงผลลัพธ์ของเมธอดที่ทำเครื่องหมายด้วย @Nullable โดยไม่ตรวจสอบก่อนว่าผลลัพธ์เป็น Null หรือไม่จะสร้างคำเตือนเกี่ยวกับ Null ใช้ @Nullable กับค่าที่แสดงผลของเมธอดเฉพาะในกรณีที่การใช้เมธอดทุกครั้งต้องได้รับการตรวจสอบค่า Null อย่างชัดเจน
ตัวอย่างต่อไปนี้แสดงการทำงานของความสามารถในการเป็น Null โค้ดตัวอย่างไม่ได้ใช้ประโยชน์จากคำอธิบายประกอบ @NonNull เนื่องจากระบบจะเพิ่มคำอธิบายประกอบลงในไบต์โค้ดที่สร้างขึ้นโดยอัตโนมัติเมื่อมีการระบุประเภทที่ไม่มีค่า Null ดังนี้
// ... /** Annotation not used because of the safe-call operator(?)**/ override fun onCreateView( name: String, context: Context, attrs: AttributeSet ): View? { // ... } // ...
การวิเคราะห์ความสามารถในการเป็นค่า Null
Android Studio รองรับการวิเคราะห์ความสามารถในการเป็นค่า Null เพื่ออนุมานและแทรกคำอธิบายประกอบความสามารถในการเป็นค่า Null ในโค้ดโดยอัตโนมัติ การวิเคราะห์ความสามารถในการเป็นค่า Null จะสแกนสัญญาตลอดลำดับชั้นของเมธอดในโค้ดเพื่อตรวจหาข้อมูลต่อไปนี้
- การเรียกใช้เมธอดที่แสดงผลเป็น Null ได้
- เมธอดที่ไม่ควรแสดงผลเป็น Null
- ตัวแปร เช่น ฟิลด์ ตัวแปรในเครื่อง และพารามิเตอร์ ที่อาจเป็น Null ได้
- ตัวแปร เช่น ฟิลด์ ตัวแปรเฉพาะที่ และพารามิเตอร์ ที่ไม่สามารถเก็บค่า Null ได้
จากนั้นการวิเคราะห์จะแทรกคำอธิบายประกอบ Null ที่เหมาะสมในตำแหน่งที่ตรวจพบโดยอัตโนมัติ
หากต้องการเรียกใช้การวิเคราะห์ความสามารถในการเป็นค่า Null ใน Android Studio ให้เลือกวิเคราะห์ > อนุมานค่า Null Android Studio จะแทรกคำอธิบายประกอบ Android @Nullable และ @NonNull ในตำแหน่งที่ตรวจพบในโค้ดของคุณ หลังจากเรียกใช้การวิเคราะห์ค่า Null แล้ว แนวทางปฏิบัติแนะนำคือการยืนยันคำอธิบายประกอบที่แทรก
หมายเหตุ: เมื่อเพิ่มคำอธิบายประกอบค่า Null การเติมข้อความอัตโนมัติอาจแนะนำคำอธิบายประกอบ @Nullable และ @NotNull ของ IntelliJ แทนคำอธิบายประกอบค่า Null ของ Android และอาจนำเข้าไลบรารีที่เกี่ยวข้องโดยอัตโนมัติ อย่างไรก็ตาม เครื่องมือวิเคราะห์ซอร์สโค้ดของ Android Studio จะมองหาเฉพาะคำอธิบายประกอบค่า Null ของ Android เท่านั้น เมื่อยืนยันคำอธิบายประกอบ ให้ตรวจสอบว่าโปรเจ็กต์ใช้คำอธิบายประกอบ Android Null เพื่อให้เครื่องมือตรวจสอบ Lint แจ้งเตือนคุณได้อย่างถูกต้องในระหว่างการตรวจสอบโค้ด
คำอธิบายประกอบทรัพยากร
การตรวจสอบประเภททรัพยากรมีประโยชน์เนื่องจากการอ้างอิงทรัพยากรของ Android เช่น ทรัพยากร drawable และ ทรัพยากรสตริง string จะส่งเป็นจำนวนเต็ม
โค้ดที่คาดหวังพารามิเตอร์เพื่ออ้างอิงทรัพยากรประเภทที่เฉพาะเจาะจง เช่น String สามารถส่งไปยังประเภทข้อมูลอ้างอิงที่คาดหวังของ int ได้ แต่อันที่จริงแล้วจะอ้างอิงทรัพยากรประเภทอื่น เช่น ทรัพยากร R.string
ตัวอย่างเช่น เพิ่มคำอธิบายประกอบ @StringRes เพื่อตรวจสอบว่าพารามิเตอร์ทรัพยากรมีการอ้างอิง R.string หรือไม่ ดังที่แสดงที่นี่
abstract fun setTitle(@StringRes resId: Int)
ในระหว่างการตรวจสอบโค้ด คำอธิบายประกอบจะสร้างคำเตือนหากไม่มีการส่งการอ้างอิง R.string ในพารามิเตอร์
คุณสามารถเพิ่มคำอธิบายประกอบสำหรับทรัพยากรประเภทอื่นๆ เช่น @DrawableRes, @DimenRes, @ColorRes และ @InterpolatorRes ได้โดยใช้รูปแบบคำอธิบายประกอบเดียวกันและเรียกใช้ระหว่างการตรวจสอบโค้ด
หากพารามิเตอร์รองรับประเภททรัพยากรหลายประเภท คุณสามารถใส่คำอธิบายประกอบประเภททรัพยากรมากกว่า 1 รายการในพารามิเตอร์ที่กำหนดได้ ใช้ @AnyRes
เพื่อระบุว่าพารามิเตอร์ที่มีคำอธิบายประกอบสามารถเป็นทรัพยากร R ประเภทใดก็ได้
แม้ว่าคุณจะใช้ @ColorRes เพื่อระบุว่าพารามิเตอร์ควรเป็นทรัพยากรสีได้ แต่ระบบจะไม่รู้จักจำนวนเต็มสี (ในรูปแบบ RRGGBB หรือ AARRGGBB) เป็นทรัพยากรสี แต่ให้ใช้คำอธิบายประกอบ @ColorInt เพื่อระบุว่าพารามิเตอร์ต้องเป็นจำนวนเต็มสีแทน เครื่องมือสร้างจะแจ้งโค้ดที่ไม่ถูกต้องซึ่งส่งรหัสทรัพยากรสี เช่น android.R.color.black ไปยังเมธอดที่มีคำอธิบายประกอบ แทนที่จะเป็นจำนวนเต็มสี
คำอธิบายประกอบชุดข้อความ
คำอธิบายประกอบเทรดจะตรวจสอบว่ามีการเรียกใช้เมธอดจากเทรดประเภทใดประเภทหนึ่งหรือไม่ ระบบรองรับคำอธิบายประกอบชุดข้อความต่อไปนี้
เครื่องมือสร้างจะถือว่าคำอธิบายประกอบ @MainThread และ @UiThread ใช้แทนกันได้ คุณจึงเรียกใช้เมธอด @UiThread จากเมธอด @MainThread ได้ และในทางกลับกัน อย่างไรก็ตาม เธรด UI อาจแตกต่างจากเธรดหลักได้ในกรณีที่เป็นแอประบบที่มีหลายมุมมองในเธรดที่ต่างกัน ดังนั้น คุณควรใส่คำอธิบายประกอบเมธอดที่เชื่อมโยงกับลำดับชั้นการแสดงผลของแอปด้วย @UiThread และใส่คำอธิบายประกอบเฉพาะเมธอดที่เชื่อมโยงกับวงจรของแอปด้วย @MainThread
หากเมธอดทั้งหมดในคลาสใช้ข้อกำหนดการแยกชุดข้อความเดียวกัน คุณสามารถเพิ่มคำอธิบายประกอบชุดข้อความเดียวลงในคลาสเพื่อยืนยันว่าเมธอดทั้งหมดในคลาสได้รับการเรียกจากชุดข้อความประเภทเดียวกัน
การใช้คำอธิบายประกอบชุดข้อความที่พบบ่อยคือการตรวจสอบว่าเมธอดหรือคลาสที่มีคำอธิบายประกอบ @WorkerThread มีการเรียกใช้จากชุดข้อความที่ทำงานอยู่เบื้องหลังที่เหมาะสมเท่านั้น
คำอธิบายประกอบข้อจำกัดของค่า
ใช้คำอธิบายประกอบ @IntRange, @FloatRange และ @Size เพื่อตรวจสอบค่าของพารามิเตอร์ที่ส่งมา ทั้ง @IntRange และ @FloatRange จะมีประโยชน์มากที่สุดเมื่อใช้กับพารามิเตอร์ที่ผู้ใช้มีแนวโน้มที่จะระบุช่วงผิด
คำอธิบายประกอบ @IntRange จะตรวจสอบว่าค่าพารามิเตอร์จำนวนเต็มหรือแบบยาวอยู่ภายในช่วงที่ระบุ ตัวอย่างต่อไปนี้แสดงให้เห็นว่าพารามิเตอร์ alpha ต้องมีค่าจำนวนเต็มตั้งแต่ 0 ถึง 255
fun setAlpha(@IntRange(from = 0, to = 255) alpha: Int) { // ... }
คำอธิบายประกอบ @FloatRange จะตรวจสอบว่าค่าพารามิเตอร์ Float หรือ Double อยู่ในช่วงค่าจุดลอยตัวที่ระบุหรือไม่ ตัวอย่างต่อไปนี้ระบุว่าพารามิเตอร์ alpha ต้องมีค่าจำนวนจริงตั้งแต่ 0.0 ถึง 1.0
fun setAlpha(@FloatRange(from = 0.0, to = 1.0) alpha: Float) { // ... }
คำอธิบายประกอบ @Size จะตรวจสอบขนาดของคอลเล็กชันหรืออาร์เรย์ หรือความยาวของสตริง คุณใช้คำอธิบายประกอบ @Size เพื่อยืนยันคุณภาพต่อไปนี้ได้
- ขนาดขั้นต่ำ เช่น
@Size(min=2) - ขนาดสูงสุด เช่น
@Size(max=2) - ขนาดที่แน่นอน เช่น
@Size(2) - ตัวเลขที่ขนาดต้องเป็นจำนวนเท่า เช่น
@Size(multiple=2)
ตัวอย่างเช่น @Size(min=1)
จะตรวจสอบว่าคอลเล็กชันไม่ว่างเปล่า และ @Size(3)
จะตรวจสอบว่าอาร์เรย์มีค่า 3 ค่าพอดี
ตัวอย่างต่อไปนี้แสดงให้เห็นว่าอาร์เรย์ location ต้องมีองค์ประกอบอย่างน้อย 1 รายการ
fun getLocation(button: View, @Size(min = 1) location: IntArray) { button.getLocationOnScreen(location) }
คำอธิบายประกอบสิทธิ์
ใช้คำอธิบายประกอบ @RequiresPermission เพื่อตรวจสอบสิทธิ์ของผู้เรียกใช้เมธอด หากต้องการตรวจสอบสิทธิ์เดียวจากรายการสิทธิ์ที่ถูกต้อง ให้ใช้แอตทริบิวต์ anyOf หากต้องการตรวจสอบชุดสิทธิ์ ให้ใช้แอตทริบิวต์ allOf ตัวอย่างต่อไปนี้จะใส่คำอธิบายประกอบเมธอด setWallpaper() เพื่อระบุว่าผู้เรียกใช้เมธอดต้องมีสิทธิ์ permission.SET_WALLPAPERS
@RequiresPermission(Manifest.permission.SET_WALLPAPER) @Throws(IOException::class) abstract fun setWallpaper(bitmap: Bitmap)
ตัวอย่างต่อไปนี้กำหนดให้ผู้เรียกใช้เมธอด copyImageFile() ต้องมีทั้งสิทธิ์อ่านในที่จัดเก็บข้อมูลภายนอกและสิทธิ์อ่านข้อมูลเมตาตำแหน่งในรูปภาพที่คัดลอกมา
@RequiresPermission( allOf = [ Manifest.permission.READ_EXTERNAL_STORAGE, Manifest.permission.ACCESS_MEDIA_LOCATION ] ) fun copyImageFile(dest: String, source: String) { // ... }
สำหรับสิทธิ์ใน Intent ให้วางข้อกำหนดสิทธิ์ในช่องสตริงที่กำหนดชื่อการดำเนินการของ Intent ดังนี้
@RequiresPermission(android.Manifest.permission.BLUETOOTH) const val ACTION_REQUEST_DISCOVERABLE = "android.bluetooth.adapter.action.REQUEST_DISCOVERABLE"
สำหรับสิทธิ์ใน Content Provider ที่ต้องใช้สิทธิ์แยกต่างหากสำหรับการเข้าถึงแบบอ่านและเขียน ให้รวมข้อกำหนดสิทธิ์แต่ละรายการไว้ในคำอธิบายประกอบ @RequiresPermission.Read หรือ @RequiresPermission.Write ดังนี้
@RequiresPermission.Read(RequiresPermission(READ_HISTORY_BOOKMARKS)) @RequiresPermission.Write(RequiresPermission(WRITE_HISTORY_BOOKMARKS)) val BOOKMARKS_URI = Uri.parse("content://browser/bookmarks")
สิทธิ์โดยอ้อม
เมื่อสิทธิ์ขึ้นอยู่กับค่าที่เฉพาะเจาะจงซึ่งระบุไว้ในพารามิเตอร์ของเมธอด ให้ใช้ @RequiresPermission ในพารามิเตอร์เองโดยไม่ต้องระบุสิทธิ์ที่เฉพาะเจาะจง
เช่น เมธอด startActivity(Intent)
ใช้สิทธิ์ทางอ้อมใน Intent ที่ส่งไปยังเมธอด ดังนี้
abstract fun startActivity(@RequiresPermission intent: Intent, bundle: Bundle?)
เมื่อคุณใช้สิทธิ์ทางอ้อม เครื่องมือสร้างจะทำการวิเคราะห์โฟลว์ข้อมูลเพื่อตรวจสอบว่าอาร์กิวเมนต์ที่ส่งไปยังเมธอดมีคำอธิบายประกอบ @RequiresPermission หรือไม่ จากนั้นจึงบังคับใช้คำอธิบายประกอบที่มีอยู่จากพารามิเตอร์ในเมธอดเอง ในตัวอย่าง startActivity(Intent) คำอธิบายประกอบในคลาส Intent จะทำให้เกิดคำเตือนที่ได้จากการใช้ startActivity(Intent) ที่ไม่ถูกต้องเมื่อมีการส่ง Intent ที่ไม่มีสิทธิ์ที่เหมาะสมไปยังเมธอด ดังที่แสดงในรูปที่ 1
รูปที่ 1 คำเตือนที่สร้างขึ้นจากคำอธิบายประกอบสิทธิ์ทางอ้อมในเมธอด startActivity(Intent)
เครื่องมือสร้างจะสร้างคำเตือนใน startActivity(Intent) จากคำอธิบายประกอบในชื่อการดำเนินการตาม Intent ที่เกี่ยวข้องในคลาส Intent ดังนี้
@RequiresPermission(Manifest.permission.CALL_PHONE) const val ACTION_CALL = "android.intent.action.CALL"
หากจำเป็น คุณสามารถใช้ @RequiresPermission แทน @RequiresPermission.Read หรือ @RequiresPermission.Write ได้เมื่อใส่คำอธิบายประกอบพารามิเตอร์ของเมธอด อย่างไรก็ตาม สำหรับสิทธิ์ทางอ้อม ไม่ควรใช้ @RequiresPermission ร่วมกับคำอธิบายประกอบสิทธิ์อ่านหรือสิทธิ์เขียน
คำอธิบายประกอบค่าที่แสดงผล
ใช้คำอธิบายประกอบ @CheckResult เพื่อตรวจสอบว่ามีการใช้ผลลัพธ์หรือค่าที่แสดงผลของเมธอดจริง แทนที่จะใส่คำอธิบายประกอบเมธอดที่ไม่ใช่โมฆะทุกเมธอดด้วย @CheckResult ให้เพิ่มคำอธิบายประกอบเพื่อชี้แจงผลลัพธ์ของเมธอดที่อาจทำให้สับสน
ตัวอย่างเช่น นักพัฒนาซอฟต์แวร์ Java มือใหม่มักเข้าใจผิดว่า <String>.trim() จะนำช่องว่างออกจากสตริงเดิม การใส่คำอธิบายประกอบเมธอดด้วย @CheckResult จะแจ้งการใช้ <String>.trim() ที่ผู้เรียกไม่ได้ดำเนินการใดๆ กับค่าที่แสดงผลของเมธอด
ตัวอย่างต่อไปนี้จะใส่คำอธิบายประกอบเมธอด checkPermissions() เพื่อตรวจสอบว่ามีการอ้างอิงค่าที่แสดงผลของเมธอดจริงหรือไม่ นอกจากนี้ยังระบุชื่อเมธอด enforcePermission() เป็นเมธอดที่จะแนะนำให้นักพัฒนาแอปใช้แทนด้วย
@CheckResult(suggest = "#enforcePermission(String,int,int,String)") abstract fun checkPermission(permission: String, pid: Int, uid: Int): Int
คำอธิบายประกอบ CallSuper
ใช้คำอธิบายประกอบ @CallSuper เพื่อตรวจสอบว่าเมธอดที่ลบล้างมีการเรียกใช้เมธอดระดับสูงของการใช้งานเมธอด
ตัวอย่างต่อไปนี้จะใส่คำอธิบายประกอบเมธอด onCreate() เพื่อให้แน่ใจว่าการติดตั้งใช้งานเมธอดที่ลบล้างจะเรียกใช้ super.onCreate()
@CallSuper override fun onCreate(savedInstanceState: Bundle?) { }
คำอธิบายประกอบ Typedef
คำอธิบายประกอบ Typedef จะตรวจสอบว่าพารามิเตอร์ ค่าที่แสดงผล หรือฟิลด์หนึ่งๆ อ้างอิงชุดค่าคงที่ที่เฉพาะเจาะจงหรือไม่ นอกจากนี้ยังเปิดใช้การเติมโค้ดให้สมบูรณ์เพื่อเสนอค่าคงที่ที่อนุญาตโดยอัตโนมัติด้วย
ใช้คำอธิบายประกอบ @IntDef และ @StringDef เพื่อสร้างคำอธิบายประกอบแบบแจกแจงของชุดจำนวนเต็มและสตริงเพื่อตรวจสอบการอ้างอิงโค้ดประเภทอื่นๆ
คำอธิบายประกอบ Typedef ใช้ @interface เพื่อประกาศประเภทคำอธิบายประกอบที่แจกแจงใหม่
คำอธิบายประกอบ @IntDef และ @StringDef พร้อมกับ @Retention จะใส่คำอธิบายประกอบใหม่และจำเป็นสำหรับการกำหนดประเภทที่แจกแจง คำอธิบายประกอบ @Retention(RetentionPolicy.SOURCE) จะบอกคอมไพเลอร์ไม่ให้จัดเก็บข้อมูลคำอธิบายประกอบที่แจกแจงไว้ในไฟล์ .class
ตัวอย่างต่อไปนี้แสดงขั้นตอนในการสร้างคำอธิบายประกอบที่ตรวจสอบว่าค่าที่ส่งเป็นพารามิเตอร์เมธอดอ้างอิงค่าคงที่ที่กำหนดไว้ค่าใดค่าหนึ่งหรือไม่
// import androidx.annotation.IntDef // ... // Define the list of accepted constants and declare the NavigationMode annotation. @Retention(AnnotationRetention.SOURCE) @IntDef(NAVIGATION_MODE_STANDARD, NAVIGATION_MODE_LIST, NAVIGATION_MODE_TABS) annotation class NavigationMode // Declare the constants. const val NAVIGATION_MODE_STANDARD = 0 const val NAVIGATION_MODE_LIST = 1 const val NAVIGATION_MODE_TABS = 2 abstract class ActionBar { // Decorate the target methods with the annotation. // Attach the annotation. @get:NavigationMode @setparam:NavigationMode abstract var navigationMode: Int }
เมื่อคุณสร้างโค้ดนี้ ระบบจะสร้างคำเตือนหากพารามิเตอร์ mode ไม่อ้างอิงค่าคงที่ที่กำหนดไว้ (NAVIGATION_MODE_STANDARD, NAVIGATION_MODE_LIST หรือ NAVIGATION_MODE_TABS)
รวม @IntDef และ @IntRange เพื่อระบุว่าจำนวนเต็มอาจเป็นชุดค่าคงที่ที่กำหนดหรือค่าภายในช่วงก็ได้
เปิดใช้การรวมค่าคงที่กับแฟล็ก
หากผู้ใช้สามารถรวมค่าคงที่ที่อนุญาตเข้ากับแฟล็ก (เช่น |, &, ^ และอื่นๆ) คุณสามารถกำหนดคำอธิบายประกอบด้วยแอตทริบิวต์ flag เพื่อตรวจสอบว่าพารามิเตอร์หรือค่าที่แสดงผลอ้างอิงรูปแบบที่ถูกต้องหรือไม่
ตัวอย่างต่อไปนี้สร้างคำอธิบายประกอบ DisplayOptions ที่มีรายการค่าคงที่ DISPLAY_ ที่ถูกต้อง
// import androidx.annotation.IntDef // ... @IntDef( flag = true, value = [ DISPLAY_USE_LOGO, DISPLAY_SHOW_HOME, DISPLAY_HOME_AS_UP, DISPLAY_SHOW_TITLE, DISPLAY_SHOW_CUSTOM ] ) @Retention(AnnotationRetention.SOURCE) annotation class DisplayOptions // ...
เมื่อคุณสร้างโค้ดที่มีแฟล็กคำอธิบายประกอบ ระบบจะสร้างคำเตือนหากพารามิเตอร์ที่ตกแต่งหรือค่าที่แสดงผลไม่ได้อ้างอิงรูปแบบที่ถูกต้อง
เก็บคำอธิบายประกอบไว้
คำอธิบายประกอบ @Keep ช่วยให้มั่นใจได้ว่าระบบจะไม่นำคลาสหรือเมธอดที่มีคำอธิบายประกอบออกเมื่อมีการลดขนาดโค้ดในเวลาบิลด์ โดยทั่วไปแล้ว ระบบจะเพิ่มคำอธิบายประกอบนี้ลงในเมธอดและคลาสที่เข้าถึงผ่านการสะท้อนเพื่อป้องกันไม่ให้คอมไพเลอร์ถือว่าโค้ดไม่ได้ใช้
ข้อควรระวัง: คลาสและเมธอดที่คุณใส่คำอธิบายประกอบโดยใช้ @Keep จะปรากฏใน APK ของแอปเสมอ แม้ว่าคุณจะไม่เคยอ้างอิงคลาสและเมธอดเหล่านี้ภายในตรรกะของแอปก็ตาม
หากต้องการให้แอปมีขนาดเล็ก ให้พิจารณาว่าจำเป็นต้องเก็บคำอธิบายประกอบ @Keep แต่ละรายการไว้ในแอปหรือไม่ หากคุณใช้การสะท้อนเพื่อเข้าถึงคลาสหรือเมธอดที่มีคำอธิบายประกอบ ให้ใช้เงื่อนไข -if ในกฎ ProGuard โดยระบุคลาสที่ทำการเรียกการสะท้อน
ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีลดขนาดโค้ดและระบุโค้ดที่ไม่ควรนำออกได้ที่ย่อ ปรับให้ยากต่อการอ่าน และเพิ่มประสิทธิภาพแอป
คำอธิบายประกอบระดับการเข้าถึงโค้ด
ใช้คำอธิบายประกอบต่อไปนี้เพื่อระบุระดับการเข้าถึงโค้ดบางส่วนที่เฉพาะเจาะจง เช่น เมธอด คลาส ฟิลด์ หรือแพ็กเกจ
แสดงโค้ดสำหรับการทดสอบ
คำอธิบายประกอบ
@VisibleForTesting
ระบุว่าเมธอดที่มีคำอธิบายประกอบจะมองเห็นได้มากกว่าที่จำเป็นตามปกติเพื่อให้เมธอดนั้นทดสอบได้ คำอธิบายประกอบนี้มีอาร์กิวเมนต์ otherwise ที่ไม่บังคับซึ่งช่วยให้คุณกำหนดระดับการเข้าถึงของเมธอดได้ หากไม่จำเป็นต้องทำให้มองเห็นได้สำหรับการทดสอบ Lint ใช้อาร์กิวเมนต์ otherwise เพื่อบังคับใช้ระดับการเข้าถึงที่ต้องการ
ในตัวอย่างต่อไปนี้ โดยปกติแล้ว myMethod() จะเป็น private แต่จะเป็น package-private สำหรับการทดสอบ เมื่อมีการกำหนด VisibleForTesting.PRIVATE Lint จะแสดงข้อความหากมีการเรียกใช้เมธอดนี้จากภายนอกบริบทที่ได้รับอนุญาตโดยการเข้าถึง private เช่น จากหน่วยการคอมไพล์อื่น
@VisibleForTesting(otherwise = VisibleForTesting.PRIVATE) fun myMethod() { // ... }
นอกจากนี้ คุณยังระบุ @VisibleForTesting(otherwise = VisibleForTesting.NONE) เพื่อระบุว่ามีเมธอดสำหรับการทดสอบเท่านั้นได้ด้วย รูปแบบนี้เหมือนกับการใช้ @RestrictTo(TESTS) ทั้ง 2 วิธีจะทำการตรวจสอบ Lint เหมือนกัน
จำกัด API
คำอธิบายประกอบ @RestrictTo บ่งชี้ว่าการเข้าถึง API ที่มีคำอธิบายประกอบ (แพ็กเกจ คลาส หรือเมธอด) ถูกจำกัด ดังนี้
คลาสย่อย
ใช้รูปแบบคำอธิบายประกอบ @RestrictTo(RestrictTo.Scope.SUBCLASSES) เพื่อจำกัดการเข้าถึง API เฉพาะคลาสย่อยเท่านั้น
เฉพาะคลาสที่ขยายคลาสที่มีคำอธิบายประกอบเท่านั้นที่เข้าถึง API นี้ได้ ตัวแก้ไข protected ของ Java ไม่มีการจำกัดที่เพียงพอ เนื่องจากอนุญาตให้เข้าถึงจากคลาสที่ไม่เกี่ยวข้องภายในแพ็กเกจเดียวกัน นอกจากนี้ ยังมีบางกรณีที่คุณต้องการปล่อย
เมธอด public ไว้เพื่อความยืดหยุ่นในอนาคต เนื่องจากคุณไม่สามารถทำให้เมธอด ที่เคยเป็น
protected และถูกลบล้างไปแล้วกลับมาเป็น public ได้ แต่คุณต้องการบอก
ใบ้ว่าคลาสนั้นมีไว้เพื่อใช้งานภายในคลาสหรือจากคลาสย่อยเท่านั้น
ห้องสมุด
ใช้แบบฟอร์มคำอธิบายประกอบ @RestrictTo(RestrictTo.Scope.LIBRARY_GROUP_PREFIX) เพื่อจำกัดการเข้าถึง API ให้เฉพาะไลบรารีของคุณเท่านั้น
มีเพียงโค้ดไลบรารีของคุณเท่านั้นที่เข้าถึง API ที่มีคำอธิบายประกอบได้ ซึ่งช่วยให้คุณไม่เพียงจัดระเบียบโค้ดในลำดับชั้นแพ็กเกจที่ต้องการได้เท่านั้น แต่ยังแชร์โค้ดระหว่างกลุ่มไลบรารีที่เกี่ยวข้องได้ด้วย ตัวเลือกนี้มีให้บริการอยู่แล้วสำหรับไลบรารี Jetpack ที่มีโค้ดการใช้งานจำนวนมากซึ่งไม่ได้มีไว้สำหรับการใช้งานภายนอก แต่ต้องเป็น public เพื่อแชร์ในไลบรารี Jetpack เสริมต่างๆ
การทดสอบ
ใช้แบบฟอร์มคำอธิบายประกอบ @RestrictTo(RestrictTo.Scope.TESTS) เพื่อป้องกันไม่ให้นักพัฒนาแอปรายอื่นเข้าถึง API การทดสอบของคุณ
มีเพียงโค้ดทดสอบเท่านั้นที่เข้าถึง API ที่มีคำอธิบายประกอบได้ ซึ่งจะช่วยป้องกันไม่ให้นักพัฒนาแอปรายอื่นใช้ API สำหรับการพัฒนาที่คุณตั้งใจจะใช้เพื่อการทดสอบเท่านั้น