การใช้เครื่องมือตรวจสอบโค้ด เช่น Lint จะช่วยคุณค้นหาปัญหาและปรับปรุงโค้ดได้ แต่เครื่องมือตรวจสอบจะอนุมานได้เพียงเท่านี้ ตัวอย่างเช่น รหัสทรัพยากร Android ใช้ int
เพื่อระบุสตริง กราฟิก สี และทรัพยากรประเภทอื่นๆ เครื่องมือตรวจสอบจึงไม่สามารถบอกได้ว่าคุณระบุทรัพยากรสตริงในตำแหน่งที่ควรระบุสี สถานการณ์นี้หมายความว่าแอปอาจแสดงผลอย่างไม่ถูกต้องหรือไม่ทำงานเลย แม้ว่าคุณจะใช้การตรวจสอบโค้ดก็ตาม
คําอธิบายประกอบช่วยให้คุณระบุคำแนะนำแก่เครื่องมือตรวจสอบโค้ด เช่น Lint เพื่อช่วยตรวจหาปัญหาโค้ดที่ละเอียดยิ่งขึ้น ระบบจะเพิ่มคำอธิบายประกอบเป็นแท็กข้อมูลเมตาที่คุณแนบกับตัวแปร พารามิเตอร์ และค่าที่แสดงผลเพื่อตรวจสอบค่าที่แสดงผลของเมธอด พารามิเตอร์ที่ส่ง ตัวแปรภายใน และช่อง เมื่อใช้กับเครื่องมือตรวจสอบโค้ด คำอธิบายประกอบสามารถช่วยคุณตรวจหาปัญหาได้ เช่น ข้อยกเว้นของตัวชี้ Null และความขัดแย้งของประเภททรัพยากร
Android รองรับคำอธิบายประกอบที่หลากหลายผ่านคลังคำอธิบายประกอบของ Jetpack
คุณสามารถเข้าถึงคลังผ่านแพ็กเกจ androidx.annotation
ได้
หมายเหตุ: หากโมดูลมีการพึ่งพาเครื่องประมวลผลคำอธิบายประกอบ คุณต้องใช้การกำหนดค่าการพึ่งพา kapt
หรือ ksp
สำหรับ Kotlin หรือการกำหนดค่าการพึ่งพา annotationProcessor
สำหรับ Java เพื่อเพิ่มการพึ่งพานั้น
เพิ่มคำอธิบายประกอบลงในโปรเจ็กต์
หากต้องการเปิดใช้คำอธิบายประกอบในโปรเจ็กต์ ให้เพิ่มandroidx.annotation:annotation
ข้อกําหนดในไลบรารีหรือแอป ระบบจะตรวจสอบคำอธิบายประกอบที่คุณเพิ่มเมื่อเรียกใช้การตรวจสอบโค้ดหรืองาน lint
เพิ่มการพึ่งพาไลบรารีคำอธิบายประกอบของ Jetpack
ไลบรารี Jetpack Analytics เผยแพร่ใน Maven Repository ของ Google
หากต้องการเพิ่มไลบรารีการกำกับเนื้อหาของ Jetpack ลงในโปรเจ็กต์ ให้ใส่บรรทัดต่อไปนี้ในบล็อก dependencies
ของไฟล์ build.gradle
หรือ build.gradle.kts
dependencies { implementation("androidx.annotation:annotation:1.9.1") }
dependencies { implementation 'androidx.annotation:annotation:1.9.1' }
หากคุณใช้คำอธิบายประกอบในโมดูลไลบรารีของคุณเอง คำอธิบายประกอบจะรวมอยู่ในอาร์ติแฟกต์ไฟล์เก็บถาวร Android (AAR) ในรูปแบบ XML ในไฟล์ annotations.zip
การเพิ่มข้อกําหนดของ androidx.annotation
จะไม่ทําให้ผู้ใช้ปลายทางของคลังของคุณต้องมีข้อกําหนด
หมายเหตุ: หากใช้ไลบรารี Jetpack อื่นๆ คุณอาจไม่จําเป็นต้องเพิ่มข้อกําหนด androidx.annotation
เนื่องจากไลบรารี Jetpack อื่นๆ จำนวนมากอาศัยไลบรารีคำอธิบายประกอบ คุณจึงอาจมีสิทธิ์เข้าถึงคำอธิบายประกอบอยู่แล้ว
ดูรายการคำอธิบายประกอบทั้งหมดที่รวมอยู่ในที่เก็บ Jetpack ได้ที่ข้อมูลอ้างอิงไลบรารีคำอธิบายประกอบของ Jetpack หรือใช้ฟีเจอร์เติมข้อความอัตโนมัติเพื่อแสดงตัวเลือกที่มีอยู่สำหรับคำสั่ง import androidx.annotation.
เรียกใช้การตรวจสอบโค้ด
หากต้องการเริ่มการตรวจสอบโค้ดจาก Android Studio ซึ่งประกอบด้วยการตรวจสอบคำอธิบายประกอบและการตรวจสอบ Lint อัตโนมัติ ให้เลือกวิเคราะห์ > ตรวจสอบโค้ดจากเมนู Android Studio จะแสดงข้อความความขัดแย้งเพื่อแจ้งปัญหาที่อาจเกิดขึ้นเมื่อโค้ดของคุณขัดแย้งกับคำอธิบายประกอบ และเพื่อแนะนำวิธีแก้ปัญหาที่เป็นไปได้
นอกจากนี้ คุณยังบังคับใช้คำอธิบายประกอบได้โดยเรียกใช้งาน lint
โดยใช้บรรทัดคำสั่ง แม้ว่าวิธีนี้อาจมีประโยชน์สำหรับการแจ้งปัญหาเกี่ยวกับเซิร์ฟเวอร์การผสานรวมอย่างต่อเนื่อง แต่งาน lint
จะไม่บังคับใช้คำอธิบายประกอบเกี่ยวกับค่าว่าง (อธิบายไว้ในส่วนถัดไป) มีเพียง Android Studio เท่านั้นที่บังคับใช้ ดูข้อมูลเพิ่มเติมเกี่ยวกับการเปิดใช้และเรียกใช้การตรวจสอบ Lint ได้ที่การปรับปรุงโค้ดด้วยการตรวจสอบ Lint
แม้ว่าข้อขัดแย้งของคำอธิบายประกอบจะสร้างคำเตือน แต่จะไม่ขัดขวางการคอมไพล์แอป
คำอธิบายประกอบ Null
คำอธิบายประกอบ Null จะมีประโยชน์ในโค้ด Java เพื่อบังคับใช้ว่าค่าเป็น Null หรือไม่ แต่จะใช้ในโค้ด Kotlin ได้น้อยลง เนื่องจาก Kotlin มีกฎเกี่ยวกับ Nullability ในตัวซึ่งบังคับใช้ขณะคอมไพล์เพิ่มการกำกับเนื้อหา @Nullable
และ @NonNull
เพื่อตรวจสอบว่าตัวแปร พารามิเตอร์ หรือค่าที่แสดงผลเป็นค่าว่างหรือไม่ คําอธิบายประกอบ @Nullable
ระบุตัวแปร พารามิเตอร์ หรือค่าที่แสดงผลซึ่งอาจเป็นค่าว่างได้
@NonNull
บ่งบอกถึงตัวแปร พารามิเตอร์ หรือค่าที่ส่งคืนต้องไม่เป็นค่าว่าง
เช่น หากมีการส่งตัวแปรภายในซึ่งมีค่า Null เป็นพารามิเตอร์ไปยังเมธอดที่มีคำอธิบายประกอบ @NonNull
แนบอยู่กับพารามิเตอร์นั้น การสร้างโค้ดจะสร้างคำเตือนที่ระบุว่ามีความขัดแย้งที่ไม่ใช่ Null นอกจากนี้ การพยายามอ้างอิงผลลัพธ์ของเมธอดที่มีเครื่องหมาย @Nullable
โดยไม่ตรวจสอบก่อนว่าผลลัพธ์เป็น Null หรือไม่ จะทำให้เกิดคำเตือนเกี่ยวกับค่า Null ใช้ @Nullable
กับค่าผลลัพธ์ของเมธอดก็ต่อเมื่อต้องทำเครื่องหมายการใช้เมธอดดังกล่าวอย่างชัดแจ้ง
ตัวอย่างต่อไปนี้แสดงการใช้งาน Nullability โค้ดตัวอย่างของ Kotlin จะไม่ใช้ประโยชน์จากคำอธิบายประกอบ @NonNull
เนื่องจากมีการเพิ่มลงในไบต์โค้ดที่สร้างขึ้นโดยอัตโนมัติเมื่อระบุประเภทที่ไม่เป็น Nullable ตัวอย่าง Java ใช้คําอธิบายประกอบ @NonNull
ในพารามิเตอร์ context
และ attrs
เพื่อตรวจสอบว่าค่าพารามิเตอร์ที่ส่งไม่ใช่ค่า Null และตรวจสอบว่าเมธอด onCreateView()
ไม่ได้แสดงผลลัพธ์เป็น Null ด้วย
... /** Annotation not used because of the safe-call operator(?)**/ override fun onCreateView( name: String?, context: Context, attrs: AttributeSet ): View? { ... } ...
import androidx.annotation.NonNull; ... /** Add support for inflating the <fragment> tag. **/ @NonNull @Override public View onCreateView(String name, @NonNull Context context, @NonNull AttributeSet attrs) { ... } ...
การวิเคราะห์ความสามารถในการเว้นว่าง
Android Studio รองรับการวิเคราะห์ความสามารถในการเป็น Null เพื่ออนุมานและแทรกคําอธิบายประกอบเกี่ยวกับ Nullness ในโค้ดโดยอัตโนมัติ การวิเคราะห์ความสามารถในการเป็น Null จะสแกนสัญญาตลอดลําดับชั้นเมธอดในโค้ดเพื่อตรวจหาสิ่งต่อไปนี้
- วิธีการโทรที่ส่งคืนค่า Null ได้
- เมธอดที่ไม่ควรแสดงผลลัพธ์เป็นค่าว่าง
- ตัวแปร เช่น ฟิลด์ ตัวแปรในเครื่อง พารามิเตอร์ ที่สามารถเป็นค่า Null
- ตัวแปร เช่น ช่อง ตัวแปรในเครื่อง และพารามิเตอร์ที่เก็บค่า Null ไม่ได้
จากนั้นการวิเคราะห์จะแทรกคำอธิบายประกอบ Null ที่เหมาะสมโดยอัตโนมัติในตำแหน่งที่ตรวจพบ
หากต้องการเรียกใช้การวิเคราะห์ Nullability ใน Android Studio ให้เลือกวิเคราะห์ >
อนุมาน Nullity Android Studio จะแทรกคำอธิบายประกอบ @Nullable
และ @NonNull
ของ Android ในตำแหน่งที่ตรวจพบในโค้ด หลังจากเรียกใช้การวิเคราะห์ Null แล้ว คุณควรยืนยันคำอธิบายประกอบที่แทรกเข้ามา
หมายเหตุ: เมื่อเพิ่มคำอธิบายประกอบที่ไม่มีข้อมูล การเติมข้อความอัตโนมัติอาจแนะนำคำอธิบายประกอบ IntelliJ
@Nullable
และ @NotNull
แทนคำอธิบายประกอบ Android Null และอาจนำเข้าไลบรารีที่เกี่ยวข้องโดยอัตโนมัติ อย่างไรก็ตาม เครื่องมือตรวจสอบ Lint ของ Android Studio จะค้นหาเฉพาะคำอธิบายประกอบ Android ที่ไม่มีข้อมูลเท่านั้น เมื่อยืนยันแอตทริบิวต์กำกับ ให้ตรวจสอบว่าโปรเจ็กต์ใช้แอตทริบิวต์กำกับ Null ของ Android เพื่อให้โปรแกรมตรวจสอบ Lint แจ้งให้คุณทราบอย่างถูกต้องระหว่างการตรวจสอบโค้ด
คําอธิบายประกอบทรัพยากร
การยืนยันประเภททรัพยากรอาจมีประโยชน์เนื่องจาก Android จะส่งการอ้างอิงทรัพยากร เช่น ทรัพยากร drawable และ string เป็นจำนวนเต็ม
โค้ดที่คาดหวังว่าพารามิเตอร์จะอ้างอิงทรัพยากรประเภทหนึ่งๆ เช่น String
สามารถส่งไปยังประเภทข้อมูลอ้างอิง int
ที่คาดไว้ แต่จริงๆ แล้วอ้างอิงทรัพยากรประเภทอื่น เช่น ทรัพยากร R.string
เช่น เพิ่มคำอธิบายประกอบ @StringRes
เพื่อตรวจสอบว่าพารามิเตอร์ทรัพยากรมีการอ้างอิง R.string
หรือไม่ ดังที่แสดงที่นี่
abstract fun setTitle(@StringRes resId: Int)
public abstract void setTitle(@StringRes int resId)
ในระหว่างการตรวจสอบโค้ด คําอธิบายประกอบจะสร้างคําเตือนหากไม่มีการส่ง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) { ... }
public void setAlpha(@IntRange(from=0,to=255) int alpha) { ... }
คําอธิบายประกอบ @FloatRange
จะตรวจสอบว่าค่าพารามิเตอร์ประเภท float หรือ Double อยู่ในช่วงค่าทศนิยมที่ระบุหรือไม่ ตัวอย่างต่อไปนี้ระบุว่าพารามิเตอร์ alpha
ต้องมีค่าจำนวนลอยตัวตั้งแต่ 0.0 ถึง 1.0
fun setAlpha(@FloatRange(from = 0.0, to = 1.0) alpha: Float) {...}
public void setAlpha(@FloatRange(from=0.0, to=1.0) float alpha) {...}
คําอธิบายประกอบ @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) }
void getLocation(View button, @Size(min=1) int[] location) { button.getLocationOnScreen(location); }
คําอธิบายประกอบสิทธิ์
ใช้แอตทริบิวต์ @RequiresPermission
เพื่อตรวจสอบสิทธิ์ของผู้เรียกใช้เมธอด หากต้องการตรวจสอบสิทธิ์เดียวจากรายการสิทธิ์ที่ถูกต้อง ให้ใช้แอตทริบิวต์ anyOf
หากต้องการตรวจสอบชุดสิทธิ์ ให้ใช้แอตทริบิวต์ allOf
ตัวอย่างต่อไปนี้กำกับเนื้อหาของเมธอด setWallpaper()
เพื่อระบุว่าผู้เรียกใช้เมธอดต้องมีสิทธิ์ permission.SET_WALLPAPERS
@RequiresPermission(Manifest.permission.SET_WALLPAPER) @Throws(IOException::class) abstract fun setWallpaper(bitmap: Bitmap)
@RequiresPermission(Manifest.permission.SET_WALLPAPER) public abstract void setWallpaper(Bitmap bitmap) throws IOException;
ตัวอย่างต่อไปนี้กำหนดให้ผู้เรียกใช้เมธอด copyImageFile()
ต้องมีทั้งสิทธิ์อ่านที่จัดเก็บข้อมูลภายนอกและสิทธิ์อ่านข้อมูลเมตาตำแหน่งในรูปภาพที่คัดลอก
@RequiresPermission(allOf = [ Manifest.permission.READ_EXTERNAL_STORAGE, Manifest.permission.ACCESS_MEDIA_LOCATION ]) fun copyImageFile(dest: String, source: String) { ... }
@RequiresPermission(allOf = { Manifest.permission.READ_EXTERNAL_STORAGE, Manifest.permission.ACCESS_MEDIA_LOCATION}) public static final void copyImageFile(String dest, String source) { //... }
สำหรับสิทธิ์ใน Intent ให้ใส่ข้อกําหนดสิทธิ์ในช่องสตริงที่กําหนดชื่อการดำเนินการของ Intent ดังนี้
@RequiresPermission(android.Manifest.permission.BLUETOOTH) const val ACTION_REQUEST_DISCOVERABLE = "android.bluetooth.adapter.action.REQUEST_DISCOVERABLE"
@RequiresPermission(android.Manifest.permission.BLUETOOTH) public static final String ACTION_REQUEST_DISCOVERABLE = "android.bluetooth.adapter.action.REQUEST_DISCOVERABLE";
สำหรับสิทธิ์ในผู้ให้บริการเนื้อหาที่ต้องใช้สิทธิ์แยกต่างหากสำหรับการเข้าถึงแบบอ่านและเขียน ให้ใส่ข้อกำหนดสิทธิ์แต่ละรายการไว้ในคำอธิบายประกอบ @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.Read(@RequiresPermission(READ_HISTORY_BOOKMARKS)) @RequiresPermission.Write(@RequiresPermission(WRITE_HISTORY_BOOKMARKS)) public static final Uri BOOKMARKS_URI = Uri.parse("content://browser/bookmarks");
สิทธิ์โดยอ้อม
เมื่อสิทธิ์ขึ้นอยู่กับค่าที่เฉพาะเจาะจงซึ่งระบุไว้ในพารามิเตอร์ของเมธอด ให้ใช้ @RequiresPermission
ในพารามิเตอร์นั้นๆ โดยไม่ต้องระบุสิทธิ์ที่เฉพาะเจาะจง
ตัวอย่างเช่น เมธอด startActivity(Intent)
ใช้สิทธิ์โดยอ้อมใน Intent ที่ส่งไปยังเมธอด
abstract fun startActivity(@RequiresPermission intent: Intent, bundle: Bundle?)
public abstract void startActivity(@RequiresPermission Intent intent, @Nullable 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(Manifest.permission.CALL_PHONE) public static final String ACTION_CALL = "android.intent.action.CALL";
หากจำเป็น คุณสามารถใช้ @RequiresPermission
แทน @RequiresPermission.Read
หรือ @RequiresPermission.Write
เมื่อกำกับเนื้อหาพารามิเตอร์ของเมธอด อย่างไรก็ตาม สำหรับสิทธิ์โดยอ้อม คุณไม่ควรใช้ @RequiresPermission
ร่วมกับคำอธิบายประกอบสิทธิ์การอ่านหรือเขียน
แสดงผลคำอธิบายประกอบมูลค่า
ใช้คำอธิบายประกอบ @CheckResult
เพื่อตรวจสอบว่าผลลัพธ์หรือค่าที่แสดงผลของเมธอดนั้นๆ ใช้งานได้จริง แทนที่จะกำกับเนื้อหาทุกเมธอดที่ไม่ใช่ void ด้วย @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
@CheckResult(suggest="#enforcePermission(String,int,int,String)") public abstract int checkPermission(@NonNull String permission, int pid, int uid);
คำอธิบายประกอบ CallSuper
ใช้คำอธิบายประกอบ @CallSuper
เพื่อตรวจสอบว่าเมธอดการลบล้างเรียกใช้วิธีการขั้นสูง
ตัวอย่างต่อไปนี้อธิบายประกอบเมธอด onCreate()
เพื่อให้แน่ใจว่าการใช้งานเมธอดที่ลบล้างจะเรียกใช้ super.onCreate()
@CallSuper override fun onCreate(savedInstanceState: Bundle?) { }
@CallSuper protected void onCreate(Bundle savedInstanceState) { }
คําอธิบายประกอบ 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 }
import androidx.annotation.IntDef; //... public abstract class ActionBar { //... // Define the list of accepted constants and declare the NavigationMode annotation. @Retention(RetentionPolicy.SOURCE) @IntDef({NAVIGATION_MODE_STANDARD, NAVIGATION_MODE_LIST, NAVIGATION_MODE_TABS}) public @interface NavigationMode {} // Declare the constants. public static final int NAVIGATION_MODE_STANDARD = 0; public static final int NAVIGATION_MODE_LIST = 1; public static final int NAVIGATION_MODE_TABS = 2; // Decorate the target methods with the annotation. @NavigationMode public abstract int getNavigationMode(); // Attach the annotation. public abstract void setNavigationMode(@NavigationMode int mode); }
เมื่อสร้างโค้ดนี้ ระบบจะสร้างคำเตือนหากพารามิเตอร์ mode
ไม่ได้อ้างอิงค่าคงที่ที่กำหนดไว้รายการใดรายการหนึ่ง (NAVIGATION_MODE_STANDARD
, NAVIGATION_MODE_LIST
หรือ NAVIGATION_MODE_TABS
)
รวม @IntDef
และ @IntRange
เพื่อระบุว่าจำนวนเต็มอาจเป็นชุดค่าคงที่ที่กำหนดหรือค่าภายในช่วงก็ได้
เปิดใช้การรวมค่าคงที่กับ Flag
หากผู้ใช้รวมค่าคงที่ที่อนุญาตเข้ากับแฟล็กได้ (เช่น |
, &
, ^
และอื่นๆ) คุณจะกำหนดคำอธิบายประกอบด้วยแอตทริบิวต์ 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 ...
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(RetentionPolicy.SOURCE) public @interface DisplayOptions {} ...
เมื่อคุณสร้างโค้ดที่มี Flag คำอธิบายประกอบ ระบบจะแสดงคำเตือนหากพารามิเตอร์หรือค่าที่แสดงไม่ได้อ้างอิงรูปแบบที่ถูกต้อง
เก็บคำอธิบายประกอบ
คำอธิบายประกอบ @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.PRIVATE) void myMethod() { ... }
นอกจากนี้ คุณยังระบุ @VisibleForTesting(otherwise = VisibleForTesting.NONE)
เพื่อระบุว่ามีเมธอดอยู่เพื่อทดสอบเท่านั้นได้ด้วย แบบฟอร์มนี้จะเหมือนกับการใช้ @RestrictTo(TESTS)
ทั้ง 2 รายการจะดำเนินการตรวจสอบโปรแกรมแก้ไขข้อบกพร่องแบบเดียวกัน
จำกัด 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 สําหรับการพัฒนาที่คุณตั้งใจไว้สําหรับวัตถุประสงค์การทดสอบเท่านั้น