Kotlin Academy · บทเรียน

การสร้างและกำหนดเป้าหมายคำอธิบายประกอบแบบกำหนดเอง

กำหนดคำอธิบายประกอบพร้อมนโยบายการคงอยู่ และนำไปใช้กับคลาส ฟังก์ชัน และพร็อพเพอร์ตี

การสร้างและกำหนดเป้าหมายคำอธิบายประกอบแบบกำหนดเอง เป็นบทเรียน Kotlin Academy ฟรีบน CoddyKit นี่คือบทเรียนที่ 2 จากทั้งหมด 4 บทเรียน คุณสามารถอ่านบทเรียนทั้งหมดด้านล่างฟรี — จากนั้นลองปฏิบัติด้วยตัวคุณเองในเบราว์เซอร์พร้อมตัวแก้ไขโค้ดในตัวและติวเตอร์ AI ตลอด 24/7 บทเรียนนี้เป็นส่วนหนึ่งของเส้นทางการเรียน Kotlin Academy และความก้าวหน้าของคุณจะซิงค์ข้ามเว็บและแอป CoddyKit คอร์ส Kotlin Academy มีบทเรียนทั้งหมด 4 บทเรียน

เหตุใดจึงใช้คำอธิบายประกอบแบบกำหนดเอง

คำอธิบายประกอบคือเมทาดาทาที่แนบกับการประกาศ เช่น คลาส ฟังก์ชัน คุณสมบัติ และพารามิเตอร์ คำอธิบายประกอบแบบกำหนดเองช่วยให้คุณทำเครื่องหมายโค้ดเพื่อให้เฟรมเวิร์ก เครื่องมือสร้าง เช่น KSP/KAPT หรือตรรกะขณะทำงานของคุณเองนำไปประมวลผล

การประกาศคำอธิบายประกอบ

ใช้คำสำคัญ annotation class คลาสคำอธิบายประกอบสามารถมีพารามิเตอร์ตัวสร้างได้ โดยจำกัดเฉพาะชนิดพื้นฐาน สตริง KClass ค่าจากแจกแจง คำอธิบายประกอบอื่น หรืออาร์เรย์ของสิ่งเหล่านี้เท่านั้น:

annotation class Validate(val minLength: Int = 1, val maxLength: Int = 255)

เมตาคำอธิบายประกอบ: @Target

@Target จำกัดตำแหน่งที่สามารถใช้คำอธิบายประกอบได้ เป้าหมายที่พบบ่อย ได้แก่ CLASS, FUNCTION, PROPERTY, FIELD, VALUE_PARAMETER และ CONSTRUCTOR

@Target(AnnotationTarget.PROPERTY, AnnotationTarget.VALUE_PARAMETER)
annotation class Validate(val minLength: Int = 1, val maxLength: Int = 255)

@Retention: คำอธิบายประกอบพร้อมใช้งานเมื่อใด

@Retention ควบคุมอายุการใช้งานของคำอธิบายประกอบ:

SOURCE — ถูกทิ้งหลังการคอมไพล์
BINARY — จัดเก็บไว้ในไฟล์ .class แต่ไม่สามารถมองเห็นผ่านรีเฟล็กชัน
RUNTIME — จัดเก็บไว้และมองเห็นได้ในขณะทำงาน ซึ่งเป็นค่าเริ่มต้นสำหรับกรณีการใช้งานส่วนใหญ่

@Retention(AnnotationRetention.RUNTIME)
@Target(AnnotationTarget.PROPERTY)
annotation class Validate(val minLength: Int = 1)

@Repeatable: การใช้คำอธิบายประกอบเดิมหลายครั้ง

ตามค่าเริ่มต้น คำอธิบายประกอบหนึ่งรายการสามารถใช้ได้เพียงครั้งเดียวต่อการประกาศหนึ่งรายการ ให้ทำเครื่องหมายด้วย @Repeatable เพื่ออนุญาตให้ใช้ได้หลายครั้ง:

@Repeatable
@Target(AnnotationTarget.FUNCTION)
annotation class Role(val name: String)

การใส่คำอธิบายประกอบให้ตัวสร้างและพารามิเตอร์

คุณสามารถใส่คำอธิบายประกอบให้พารามิเตอร์ของตัวสร้างและคุณสมบัติของตัวสร้างหลักได้ ใช้เป้าหมายตามตำแหน่งใช้งาน @field:, @get: หรือ @param: เพื่อควบคุมว่าองค์ประกอบใดจะได้รับคำอธิบายประกอบ:

data class User(
    @field:Validate(minLength = 2) val name: String,
    @field:Validate(minLength = 0, maxLength = 120) val email: String
)

เป้าหมายตามตำแหน่งใช้งาน

Kotlin สร้างองค์ประกอบไบต์โค้ดหลายรายการจากคุณสมบัติหนึ่งรายการ ได้แก่ ฟิลด์ ตัวอ่านค่า ตัวกำหนดค่า และพารามิเตอร์ เป้าหมายตามตำแหน่งใช้งานจะระบุว่าองค์ประกอบใดได้รับคำอธิบายประกอบ:

@field: ฟิลด์สำรอง
@get: ตัวอ่านค่า
@set: ตัวกำหนดค่า
@param: พารามิเตอร์ของตัวสร้าง

การใส่คำอธิบายประกอบให้คลาส

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

@Target(AnnotationTarget.CLASS)
@Retention(AnnotationRetention.RUNTIME)
annotation class Repository

@Repository
class UserRepository

@MustBeDocumented

การเพิ่ม @MustBeDocumented ทำให้คำอธิบายประกอบปรากฏในเอกสาร API ที่สร้างขึ้น ใช้สิ่งนี้กับคำอธิบายประกอบที่เป็นส่วนหนึ่งของสัญญา API สาธารณะของคุณ

@MustBeDocumented
@Target(AnnotationTarget.CLASS)
annotation class PublicApi(val since: String)

พารามิเตอร์ของคำอธิบายประกอบ: ค่าเริ่มต้นและอาร์เรย์

พารามิเตอร์สามารถมีค่าเริ่มต้นและรับอาร์เรย์ได้โดยใช้คำสำคัญ vararg หรือชนิดอาร์เรย์ที่ระบุโดยตรง:

annotation class Roles(vararg val value: String)

@Roles("ADMIN", "EDITOR")
class AdminPanel

พารามิเตอร์ KClass ในคำอธิบายประกอบ

คำอธิบายประกอบสามารถอ้างอิงชนิดคลาสผ่าน KClass ได้:

annotation class Serializer(val using: KClass<out Any>)

@Serializer(using = GsonAdapter::class)
class Event

ตรวจสอบอย่างรวดเร็ว

ค่า @Retention ใดทำให้คำอธิบายประกอบแบบกำหนดเองเข้าถึงได้ผ่านรีเฟล็กชันของ Kotlin ในขณะทำงาน

สรุปทบทวน: คำอธิบายประกอบแบบกำหนดเอง

ประเด็นสำคัญ:

ประกาศด้วย annotation class โดยพารามิเตอร์จำกัดเฉพาะชนิดพื้นฐาน สตริง KClass ค่าจากแจกแจง และอาร์เรย์
@Target — ตำแหน่งที่สามารถใช้ได้
@Retention — ช่วงเวลาที่พร้อมใช้งาน โดยใช้ RUNTIME สำหรับรีเฟล็กชัน
@Repeatable — อนุญาตให้ใช้หลายครั้งในการประกาศเดียว
เป้าหมายตามตำแหน่งใช้งาน เช่น @field:, @get: และอื่น ๆ ควบคุมว่าองค์ประกอบไบต์โค้ดใดจะได้รับคำอธิบายประกอบ

คำถามที่พบบ่อย

บทเรียน “การสร้างและกำหนดเป้าหมายคำอธิบายประกอบแบบกำหนดเอง” ฟรีหรือไม่

ใช่ — ข้อความเต็มของ “การสร้างและกำหนดเป้าหมายคำอธิบายประกอบแบบกำหนดเอง” ฟรีให้อ่านที่นี่บนเว็บ เพื่อปฏิบัติแบบโต้ตอบ (ตัวแก้ไขโค้ดในตัวและติวเตอร์ AI ตลอด 24/7) และปลดล็อคส่วนที่เหลือของคอร์ส Kotlin Academy ให้อัปเกรดเป็น CoddyKit PRO คอร์ส Kotlin Academy มีบทเรียนทั้งหมด 4 บทเรียน

คุณจะเรียนรู้อะไรในบทเรียน “การสร้างและกำหนดเป้าหมายคำอธิบายประกอบแบบกำหนดเอง”

กำหนดคำอธิบายประกอบพร้อมนโยบายการคงอยู่ และนำไปใช้กับคลาส ฟังก์ชัน และพร็อพเพอร์ตี คุณปฏิบัติ Kotlin Academy ด้วยโค้ดที่ใช้งานได้จริงที่คุณเรียกใช้โดยตรงในเบราว์เซอร์ และติวเตอร์ AI ตลอด 24/7 ตอบคำถามของคุณขณะที่คุณไปผ่านบทเรียน

คุณต้องมีประสบการณ์ก่อนที่จะเริ่มเรียน Kotlin Academy หรือไม่

ไม่จำเป็นต้องมีประสบการณ์มาก่อน Kotlin Academy บน CoddyKit ออกแบบมาสำหรับผู้เริ่มต้นไปจนถึงผู้เรียนขั้นสูง คุณสามารถเริ่มต้นที่นี่หรือเริ่มจากตัวแรกและเรียนด้วยความเร็วของคุณเอง นี่คือบทเรียนที่ 2 จากทั้งหมด 4 บทเรียน

บทเรียน “การสร้างและกำหนดเป้าหมายคำอธิบายประกอบแบบกำหนดเอง” ใช้เวลานานแค่ไหน

บทเรียน CoddyKit ส่วนใหญ่ใช้เวลาประมาณ 5–10 นาที แต่ละบทเรียนจึงสั้นและเป็นแบบโต้ตอบ คุณสามารถก้าวหน้าอย่างต่อเนื่องและกลับมาเรียนต่อจากตรงที่เพิ่งหยุดบนเว็บและแอปได้เลย

ฉันเขียนและรันโค้ดในบทเรียน Kotlin Academy นี้ได้ไหม

ได้ บทเรียน Kotlin Academy ทุกบทมีตัวแก้ไขโค้ดในตัว คุณจึงเขียนและรันโค้ดจริงได้เลยในเบราว์เซอร์ และได้รับข้อเสนอแนะจาก AI ในทันที — ไม่ต้องติดตั้งในเครื่องของคุณ

บทเรียนทั้งหมดในหลักสูตรนี้

Reflection ของ Kotlin: KClass, KFunction, KProperty
การสร้างและกำหนดเป้าหมายคำอธิบายประกอบแบบกำหนดเอง
การอ่านคำอธิบายประกอบขณะรันไทม์
การตรวจสอบและการจับคู่ด้วย Reflection

← กลับไปที่ Kotlin Academy