微北洋開(kāi)發(fā)白皮書
v1.0.0
2018-5-5
微北洋Android
這份文檔旨在講述微北洋的基礎(chǔ)架構(gòu)的設(shè)計(jì),以及其用法和新模塊的開(kāi)發(fā)流程規(guī)范粮宛。
模塊參考
目前代碼質(zhì)量較高的質(zhì)量有GPA(gpa2),課程表模塊(schedule2)。里面的代碼涵蓋了基礎(chǔ)庫(kù)的用法饵沧,Kotlin的高級(jí)使用方式,架構(gòu)的抽象封裝赌躺,自定義View之類狼牺,吃透兩個(gè)模塊的代碼,基本上就沒(méi)有什么可以擔(dān)心了礼患。
如果不知道從哪里做起是钥,可以先從GPA的Model層看起掠归,然后一步步追溯到View層,看處理方式悄泥》鞯剑看代碼的話,可以用兩種方法:自頂向下和自下而上的方法码泞,選用哪一種都OK兄旬。
基礎(chǔ)庫(kù)研究
內(nèi)容量最大,在做自己新功能之前所需要了解的就是:commons
庫(kù)的用法余寥,進(jìn)一步也需要多研究研究commons
的代碼設(shè)計(jì)领铐,閱讀完代碼一定會(huì)受益匪淺。
開(kāi)發(fā)指南
開(kāi)發(fā)指南從用法的角度來(lái)闡述微北洋的基礎(chǔ)庫(kù)
網(wǎng)絡(luò)請(qǐng)求
網(wǎng)絡(luò)請(qǐng)求再微北洋中統(tǒng)一使用Retrofit來(lái)做宋舷,至于Retrofit的用法绪撵,比如說(shuō)接口寫法,自行查閱官方文檔
我們需要根據(jù)后端組提供的API接口來(lái)寫對(duì)應(yīng)的interface
一般來(lái)講一個(gè)請(qǐng)求的URL是由BaseUrl + Path
組成祝蝠。比如說(shuō)https://open.twtstudio.com/api/v1/auditClass/audit
這個(gè)網(wǎng)絡(luò)請(qǐng)求音诈,我們規(guī)定BaseUrl = https://open.twtstudio.com/api/
,同時(shí)Path = v1/auditClass/audit
。因此我們的接口就可以這樣子寫:
interface AuditApi {
@GET("v1/auditClass/audit")
fun getMyAudit(@Query("user_number") userNumber: String = CommonPreferences.studentid): Deferred<CommonBody<List<AuditCourse>>>
@GET("v1/auditClass/popular")
fun getPopluarAudit(): Deferred<CommonBody<List<AuditPopluar>>>
@POST("v1/auditClass/audit")
@FormUrlEncoded
fun audit(@Field("user_number") userNumber: String, @Field("course_id") courseId: Int, @Field("info_ids") infoIds: String): Deferred<CommonBody<String>>
@DELETE("v1/auditClass/audit")
fun cancelAudit(@Query("user_number") userNumber: String, @Query("ids") ids: String): Deferred<CommonBody<String>>
companion object : AuditApi by ServiceFactory() // 暫時(shí)不要管這一行的意思 忽略就好了
}
這基本上就是Retrofit的寫法绎狭,需要提及一點(diǎn)是接口方法的返回值
比如說(shuō)這幾個(gè)例子中我們的返回值類型是Deferred<T>
是協(xié)程的返回類型(可以await
那種)细溅,之所以可以用這類型返回值,是因?yàn)槲覀冊(cè)赗etrofit初始化的時(shí)候儡嘶,加入了對(duì)應(yīng)的CallAdapter
.addCallAdapterFactory(RxJavaCallAdapterFactory.create())
.addCallAdapterFactory(CoroutineCallAdapterFactory())
//see code: com/twt/wepeiyang/commons/experimental/network/ServiceFactory.kt
不添加額外的CallAdapterFactory的話喇聊,我們?cè)诮涌谥兄荒軐?code>Call<T>的返回值,現(xiàn)在我們可以寫Deferred<T>
,Observable<T>
的返回值蹦狂。例如
@GET("v1/auditClass/audit")
fun getMyAudit(@Query("user_number") userNumber: String = CommonPreferences.studentid): Call<CommonBody<List<AuditCourse>>>
@GET("v1/auditClass/popular")
fun getPopluarAudit(): Observable<CommonBody<List<AuditPopluar>>>
再說(shuō)泛型包裝
先從微北洋的Api返回結(jié)構(gòu)說(shuō)起誓篱,規(guī)范的Api返回結(jié)構(gòu)是
{
"error_code": -1, // 這里是錯(cuò)誤碼,比如說(shuō)記錄Token過(guò)期凯楔,辦公網(wǎng)綁定錯(cuò)誤之類
"message": "", // 這里是服務(wù)器返回的錯(cuò)誤Message窜骄,比如說(shuō) ‘Token已過(guò)期’
"data": <這里是你真正需要的數(shù)據(jù)>
}
對(duì)于這種返回格式,我們客戶端也做了一套封裝來(lái)對(duì)應(yīng)
/**
* A common wrapper class of respond data from open.twtstudio.com/api.
*
* @see AuthService
*/
data class CommonBody<out T>(
val error_code: Int,
val message: String,
val data: T?
)
//所有的微北洋Api規(guī)范請(qǐng)求都要用這個(gè)東西來(lái)做
//see code : com/twt/wepeiyang/commons/experimental/network/ServiceFactory.kt
<強(qiáng)制使用>因?yàn)槟阏嬲胍臄?shù)據(jù)在data
字段里面摆屯,所有你只需要單獨(dú)寫data
內(nèi)容對(duì)于的bean
類即可邻遏,然后用泛型包裝。例如蹭課系統(tǒng)中我的一個(gè)請(qǐng)求返回的內(nèi)容是
{
"error_code": -1,
"message": "",
"data": [
{
"course_id": 53,
"course_name": "數(shù)據(jù)庫(kù)原理(雙語(yǔ))",
"college": "軟件學(xué)院",
"semester": "1",
"year": "2018",
"infos": [
{
"id": 417,
"course_id": "53",
"course_name": "數(shù)據(jù)庫(kù)原理(雙語(yǔ))",
"course_id_in_tju": "3665",
"start_week": "9",
"end_week": "16",
"start_time": "1",
"course_length": "2",
"week_day": "3",
"week_type": "3",
"building": "45",
"room": "B307",
"teacher_type": "副教授",
"teacher": "王征"
}
]
},
{
"course_id": 3,
"course_name": "有機(jī)化學(xué)B",
"college": "理學(xué)院",
"semester": "1",
"year": "2018",
"infos": [
{
"id": 42,
"course_id": "3",
"course_name": "有機(jī)化學(xué)B",
"course_id_in_tju": "3171",
"start_week": "1",
"end_week": "16",
"start_time": "2",
"course_length": "2",
"week_day": "5",
"week_type": "3",
"building": "50",
"room": "A124",
"teacher_type": "講師",
"teacher": "王元欣"
}
]
}
]
}
返回的data
字段是一個(gè)List鸥拧,因此我們只需要去寫這個(gè)List內(nèi)對(duì)象的對(duì)應(yīng)類即可
data class AuditCourse(val college: String,
@SerializedName("course_id") val courseId: Int,
@SerializedName("course_name") val courseName: String,
val year: String,
val semester: String,
val infos: List<InfoItem>)
同時(shí)在Retrofit的Api里面寫
@GET("v1/auditClass/audit")
fun getMyAudit(@Query("user_number") userNumber: String = CommonPreferences.studentid): Deferred<CommonBody<List<AuditCourse>>>
// 重點(diǎn):
Deferred<CommonBody<List<AuditCourse>>> //這種情況是CommonBody里面包著List<T>
當(dāng)然Data字段里面不是List就直接泛型包裹即可党远,比如說(shuō)辦公網(wǎng)課程表那邊
@GET("v1/classtable")
fun getClassTable(): Deferred<CommonBody<Classtable>>
所以給你講了那么多削解,別給我瞎雞兒寫B(tài)ean類了富弦,照著規(guī)范來(lái)
網(wǎng)絡(luò)請(qǐng)求Interface怎么用
Retrofit對(duì)于網(wǎng)絡(luò)請(qǐng)求的接口采用了動(dòng)態(tài)代理的機(jī)制,commons庫(kù)中對(duì)其進(jìn)行了封裝氛驮,具體用法:
-
在類外寫
val api: TjuCourseApi by ServiceFactory() // 可以寫在一個(gè)object里面腕柜,單例化 api.getClassTable()
-
可以在interface里寫一個(gè)伴生對(duì)象(同時(shí)實(shí)現(xiàn)該接口,同時(shí)被代理)
interface TjuCourseApi { @GET("v1/classtable") fun getClassTable(): Deferred<CommonBody<Classtable>> companion object : TjuCourseApi by ServiceFactory() // 伴生對(duì)象實(shí)現(xiàn)單例 } TjuCourseApi.getClassTable() // 就可以調(diào)用
推薦使用第二種,對(duì)應(yīng)的源碼在com/twt/wepeiyang/commons/experimental/network/ServiceFactory.kt
盏缤,如果你想要看懂這些的話砰蠢,你需要學(xué)Retrofit
,Kotlin 代理
,invoke() 運(yùn)算符重載
Async/await來(lái)處理網(wǎng)絡(luò)請(qǐng)求以及異步任務(wù)
目前微北洋里面的異步任務(wù)都是使用Kotlin協(xié)程來(lái)寫的。當(dāng)然如果你實(shí)在不會(huì)用唉铜,你也可以使用
Thread {
uiThread{
}
}
當(dāng)然這樣子我會(huì)Diss你
作為一個(gè)合格的項(xiàng)目開(kāi)發(fā)者台舱,你應(yīng)該使用Kotlin協(xié)程所提供的async/await
來(lái)處理問(wèn)題。在之前的文檔中潭流,我們的網(wǎng)絡(luò)請(qǐng)求的返回值是Deferred<T>
類型竞惋,至于這是個(gè)啥,請(qǐng)自己上網(wǎng)查謝謝灰嫉。附一個(gè)文章
一般的做發(fā)是拆宛,在普通環(huán)境(非協(xié)程環(huán)境)使用launch(UI){}
方法啟動(dòng)一個(gè)協(xié)程,在協(xié)程里面使用async/await
來(lái)控制讼撒。
launch (exceptionHandler + UI) {
val result = AuditApi.searchCourse(courseName).await()
// do something 這里的代碼會(huì)等待網(wǎng)絡(luò)請(qǐng)求出結(jié)果才執(zhí)行
}
比如說(shuō)我們添加一些邏輯
launch (exceptionHandler + UI) {
val result: CommonBody<String> = AuditApi.searchCourse(courseName).await()
// do something
if (result.error_code == -1) textView.text = result.data
}
協(xié)程里面的上下文:通用的有UI
CommonPool
表示協(xié)程運(yùn)行在哪個(gè)線程中浑厚,CommonPool
是一個(gè)線程池,耗時(shí)操作要在這里完成根盒,然后通過(guò)await
來(lái)協(xié)調(diào)先后钳幅。示例一段偽代碼(看個(gè)意思就行)
launch (exceptionHandler + UI) { // 主線程開(kāi)啟
val result: CommonBody<String> = AuditApi.searchCourse(courseName).await()
// do something
if (result.error_code == -1) textView.text = result.data
val dbTask = async(CommonPool) { // 異步開(kāi)啟
ScheduleDb.queryAllCourses() // 耗時(shí)操作
}
val courseList = dbTask.await()
courseList.foreach {
textView.text += it.courseName
}
}
這一段看不懂的話,多補(bǔ)補(bǔ)協(xié)程炎滞。菜是原罪
到這里贡这,你已經(jīng)會(huì)使用微北洋的基礎(chǔ)框架來(lái)發(fā)起一個(gè)網(wǎng)絡(luò)請(qǐng)求了。請(qǐng)不要另辟蹊徑厂榛,謝謝盖矫!
繼續(xù)閱讀下去,你會(huì)學(xué)到:緩存框架的用法
構(gòu)建有緩存的響應(yīng)式網(wǎng)絡(luò)請(qǐng)求
有一部分的網(wǎng)絡(luò)請(qǐng)求是需要通過(guò)添加緩存來(lái)提高用戶體驗(yàn)的击奶,比如說(shuō)新聞列表辈双,課程表之類。微北洋已經(jīng)對(duì)這種常用的緩存進(jìn)行了封裝柜砾。 這套封裝的架構(gòu)湃望,整體來(lái)講是基于LiveData來(lái)做的,所以如果要徹底了解這些痰驱,需要些預(yù)備知識(shí):LiveData鏈接
而如果僅僅是使用的話证芭,就非常簡(jiǎn)單了。
// 這是創(chuàng)建的過(guò)程
val GpaLocalCache = Cache.hawk<GpaBean>("GPA") //本地緩存使用Hawk存儲(chǔ)
// 遠(yuǎn)程數(shù)據(jù)的獲取方法:通過(guò)Retrofit網(wǎng)絡(luò)請(qǐng)求 -> 一個(gè)map操作只取data
val GpaRemoteCache = Cache.from(GpaService.Companion::get).map(CommonBody<GpaBean>::data)
// 最后把它們放在一起担映,RefreshableLiveData來(lái)幫你處理剩下的緩存問(wèn)題
val GpaLiveData = RefreshableLiveData.use(GpaLocalCache, GpaRemoteCache)
因?yàn)檫@套緩存系統(tǒng)是基于LiveData的废士,而LiveData又是響應(yīng)式的可觀測(cè)數(shù)據(jù)流,就很好用蝇完。比如說(shuō)GPA里面使用:
GpaLiveData.bindNonNull(this) {
// 每次GPALiveData的數(shù)據(jù)發(fā)生變化的時(shí)候官硝,這個(gè)閉包里面代碼就會(huì)被回調(diào)
// 回調(diào)的時(shí)機(jī)就是 獲得緩存/獲得網(wǎng)絡(luò)數(shù)據(jù)刷新/手動(dòng)刷新
it.stat.total.let {
scoreTv.text = it.score.toString()
gpaTv.text = it.gpa.toString()
creditTv.text = it.credit.toString()
}
it.data.asSequence().map(Term::stat).map {
GpaLineChartView.DataWithDetail(it.score, """
加權(quán):${it.score}
績(jī)點(diǎn):${it.gpa}
學(xué)分:${it.credit}
""".trimIndent())
}.toList().let {
gpaLineCv.dataWithDetail = it
}
// attempt to refresh chart view while new data coming
selectedTermIndex = selectedTermIndex
}
如果你可以看懂RefreshableLiveData的源碼矗蕊,你可以看到它的自動(dòng)刷新時(shí)機(jī),Activity/Fragment在Active的時(shí)候啟動(dòng)(你可以粗略的理解成oncreate
或者onresume
)氢架,你也可以手動(dòng)刷新傻咖,甚至加上刷新回調(diào)。
fun Context.simpleCallback(success: String? = "加載成功", error: String? = "發(fā)生錯(cuò)誤", refreshing: String? = "加載中"): suspend (RefreshState<*>) -> Unit =
with(this.asReference()) {
{
when (it) {
is RefreshState.Success -> if (success != null) Toasty.success(this(), success).show()
is RefreshState.Failure -> if (error != null) Toasty.error(this(), "$error ${it.throwable.message}岖研!${it.javaClass.name}").show()
is RefreshState.Refreshing -> if (refreshing != null) Toasty.normal(this(), "$refreshing...").show()
}
}
}
refreshBtn = findViewById<ImageButton>(R.id.btn_refresh).apply {
setOnClickListener {
GpaLiveData.refresh(REMOTE, callback = simpleCallback()) // 核心刷新方法
}
}
手動(dòng)調(diào)用refresh
方法即可手動(dòng)刷新
auditPopluarLiveData.refresh(CacheIndicator.LOCAL, CacheIndicator.REMOTE)
// 后面的部分表示卿操,從哪里刷新 Remote就是遠(yuǎn)程(服務(wù)器)
目前的封裝已經(jīng)可以應(yīng)對(duì)大部分常用的網(wǎng)絡(luò)請(qǐng)求,在緩存邏輯復(fù)雜的時(shí)候孙援,你也可以通過(guò)繼承RefreshableLiveData來(lái)做這個(gè)事情硬纤。例如:
// see code : com/twt/service/schedule2/model/audit/AuditApi.kt
val auditCourseLiveData = object : RefreshableLiveData<List<AuditCourse>, CacheIndicator>() {
override fun observe(owner: LifecycleOwner, observer: Observer<List<AuditCourse>>) {
super.observe(owner, observer)
AuditCourseManager.getAuditListLive().observe(owner, observer)
}
override fun refresh(vararg indicators: CacheIndicator, callback: suspend (RefreshState<CacheIndicator>) -> Unit) {
if (indicators == CacheIndicator.REMOTE) {
async(CommonPool) {
try {
AuditCourseManager.refreshAuditClasstable()
callback(RefreshState.Success(CacheIndicator.REMOTE))
} catch (e: Exception) {
e.printStackTrace()
callback(RefreshState.Failure(e))
}
}
}
}
override fun onActive() {
refresh(CacheIndicator.REMOTE)
}
override fun cancel() {
// no need to impl
}
}
組織結(jié)構(gòu)
微北洋的模塊開(kāi)發(fā)中,不會(huì)強(qiáng)制要求采用MVP架構(gòu)或者M(jìn)VVM架構(gòu)之類赃磨。在架構(gòu)的選擇上鼓勵(lì)有效的創(chuàng)新筝家,服從個(gè)人喜好。如果你對(duì)于項(xiàng)目結(jié)構(gòu)有些拿捏不定的話邻辉,可以參考gpa2
模塊或者schedule2
模塊溪王,里面做的還算不錯(cuò)。
一般來(lái)講值骇,Model層是一定要分開(kāi)的莹菱,就是說(shuō),如果是網(wǎng)絡(luò)請(qǐng)求吱瘩,數(shù)據(jù)庫(kù)操作道伟,或者緩存封裝之類的話,要單獨(dú)寫開(kāi)使碾。比如說(shuō)蜜徽,把網(wǎng)絡(luò)請(qǐng)求的interface,網(wǎng)絡(luò)請(qǐng)求緩存的包裝票摇,寫在一個(gè)kt文件中拘鞋。把各種bean類的定義(要用data class),寫在一個(gè)kt文件中矢门。把數(shù)據(jù)庫(kù)操作寫在一個(gè)kt文件中盆色。
建議最后暴露給上層(Activity/Presenter)使用的時(shí)候,做二次封裝祟剔,比如說(shuō)AuditCourseManager.kt
隔躲,建議不要讓上層直接操作數(shù)據(jù)庫(kù)網(wǎng)絡(luò)請(qǐng)求之類,尤其是數(shù)據(jù)庫(kù)
參考:課程表模塊
Schedule2
├── extensions
│ ├── ClassTableExtensions.kt
│ ├── ScheduleNetworkExtensions.kt
│ ├── StringExtensions.kt
│ └── UIExtensions.kt
├── model
│ ├── AbsClasstableProvider.kt
│ ├── CommonClassTable.kt
│ ├── MergedClassTableProvider.kt
│ ├── ScheduleDb.kt
│ ├── SchedulePref.kt
│ ├── TableData.kt
│ ├── audit // 蹭課
│ │ ├── AuditApi.kt // 蹭課Api接口相關(guān)
│ │ ├── AuditCourseManager.kt // 暴露給外面的物延,對(duì)蹭課Model做二次封裝
│ │ ├── AuditData.kt // 蹭課的數(shù)據(jù)bean類 / 數(shù)據(jù)庫(kù)Dao
│ │ └── AuditPopluar.kt // bean類
│ ├── custom
│ │ ├── CustomCourse.kt
│ │ ├── CustomCourseManager.kt // 暴露給外面的宣旱,對(duì)自定義Model做二次封裝
│ │ └── CustomCourseProvider.kt
│ ├── school
│ │ └── TjuCourse.kt
│ └── total
│ └── TotalCourseManager.kt // 暴露給外面的,對(duì)綜合的課程Model做二次封裝
└── view
├── adapter
│ ├── CommonItem.kt
│ └── ItemAdapter.kt
├── audit
│ ├── AuditActivity.kt
│ ├── AuditComponents.kt
│ └── search
│ ├── AnimationUtil.java
│ └── SearchResultActivity.kt
├── custom
│ ├── AddCustomCourseActivity.kt
│ ├── CustomComponents.kt
│ └── CustomSettingBottomFragment.kt
├── detail
│ ├── CourseDetailAdapter.kt
│ ├── CourseDetailBottomFragment.kt
│ ├── DetailComponents.kt
│ ├── MultiCourseDetailFragment.kt
│ └── WrapContentViewPager.java
├── schedule
│ ├── CourseRefreshBottomFragment.kt
│ ├── RefreshComponents.kt
│ ├── ScheduleActivity.kt
│ ├── ScheduleAdapter.kt
│ └── ScheduleDecoration.kt
├── theme
│ ├── ColorCircleView.kt
│ └── SpreadChainLayout.kt
└── week
├── WeekSelectAdapter.kt
├── WeekSquareView.kt
└── WeekTestActivity.kt
16 directories, 44 files
資源命名
一定要加前綴
一定要加前綴
一定要加前綴
比如說(shuō)GPA模塊中的一個(gè)layout
layout
├── gpa2_activity_evaluate.xml
├── gpa2_activity_gpa.xml
├── gpa2_component_sort.xml
├── gpa2_component_term.xml
├── gpa2_component_total.xml
├── gpa2_item_course.xml
└── gpa2_tv_selected_term.xml
Drawable教届,其他資源文件同理
依賴
不在特別需要的時(shí)候响鹃,不建議隨意使用第三方框架。
不在特別需要的時(shí)候案训,不適用注解處理器框架买置,實(shí)在需要的話,找組長(zhǎng)評(píng)估后考慮批準(zhǔn)/或被diss强霎。
不允許使用第三方Gradle插件忿项,實(shí)在需要的話,找組長(zhǎng)評(píng)估后考慮批準(zhǔn)/或被diss城舞。
使用第三方庫(kù)的時(shí)候轩触,未批準(zhǔn)不允許暴露給其他模塊,使用
implementation
家夺。對(duì)于微型第三方庫(kù)(只有一個(gè)或者幾個(gè)文件那種)脱柱,可以拷貝代碼將來(lái)直接使用(要保留代碼注釋頭部的開(kāi)源證書),而不是依賴模塊拉馋。
-
Support庫(kù)使用統(tǒng)一依賴榨为,使用方式參考
gpa2
/schedule2
模塊的build.gradle
[':auth', ':bike', ':commons', ':gpa2', ':schedule', ':tjulibrary', ':tjunet', ':party', ':schedule2'].each { implementation project(it) } implementation 'com.twt.service:fragmentation:1.1.0' [*supportLibraries, 'constraint-layout', 'multidex', *archLibraries, 'kotlin-stdlib', 'butterknife', 'anko'].each { implementation dependenciesMap[it] } ['lifecycle-compiler', 'butterknife-compiler'].each { annotationProcessor dependenciesMap[it] }
期望/計(jì)劃
- Recyclerview DSL使用文檔
- 普通DSL使用文檔