学习

Lab Week 8 Summary · Jimmy Huang's Blog

plain text

app/src/main/java/com/example/googlesearchlab/
├── MainActivity.kt
├── SearchResponse.kt
├── Items.kt
├── RetrofitInterface.kt
├── RetrofitObject.kt
├── ItemsRepository.kt
└── RetrofitViewModel.kt

plain text

用户输入 keyword
   ↓
Compose Button onClick
   ↓
RetrofitViewModel.customSearch(keyword)
   ↓
ItemsRepository.customSearch(keyword)
   ↓
RetrofitInterface.customSearch(key, cx, q)
   ↓
Google Custom Search API
   ↓
JSON response
   ↓
Gson converts JSON to SearchResponse
   ↓
ViewModel updates mutableStateOf
   ↓
Compose recomposes and displays snippet

xml

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">

    <uses-permission android:name="android.permission.INTERNET" />

    <application
        android:allowBackup="true"
        android:dataExtractionRules="@xml/data_extraction_rules"
        android:fullBackupContent="@xml/backup_rules"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/Theme.GoogleSearchLab"
        tools:targetApi="31">

        <activity
            android:name=".MainActivity"
            android:exported="true">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>

    </application>
</manifest>

kotlin

package com.example.googlesearchlab

import retrofit2.http.GET
import retrofit2.http.Query

interface RetrofitInterface {
    @GET("customsearch/v1")
    suspend fun customSearch(
        @Query("key") apiKey: String,
        @Query("cx") searchEngineId: String,
        @Query("q") keyword: String
    ): SearchResponse
}

kotlin

package com.example.googlesearchlab

import retrofit2.Retrofit
import retrofit2.converter.gson.GsonConverterFactory

object RetrofitObject {
    private const val BASE_URL = "https://www.googleapis.com/"

    val retrofitService: RetrofitInterface by lazy {
        val retrofit = Retrofit.Builder()
            .baseUrl(BASE_URL)
            .addConverterFactory(GsonConverterFactory.create())
            .build()

        retrofit.create(RetrofitInterface::class.java)
    }
}

kotlin

package com.example.googlesearchlab

class ItemsRepository {
    private val searchService = RetrofitObject.retrofitService

    private val API_KEY = "YOUR_API_KEY_HERE"
    private val SEARCH_ENGINE_ID = "YOUR_SEARCH_ENGINE_ID_HERE"

    suspend fun customSearch(keyword: String): SearchResponse {
        return searchService.customSearch(
            apiKey = API_KEY,
            searchEngineId = SEARCH_ENGINE_ID,
            keyword = keyword
        )
    }
}

kotlin

package com.example.googlesearchlab

import android.util.Log
import androidx.compose.runtime.mutableStateOf
import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import kotlinx.coroutines.launch

class RetrofitViewModel : ViewModel() {
    private val repository = ItemsRepository()

    val retrofitResponse = mutableStateOf(SearchResponse())
    val isLoading = mutableStateOf(false)
    val errorMessage = mutableStateOf<String?>(null)

    fun customSearch(keyword: String) {
        if (keyword.isBlank()) {
            errorMessage.value = "Please enter a keyword"
            return
        }

        viewModelScope.launch {
            isLoading.value = true
            errorMessage.value = null

            try {
                retrofitResponse.value = repository.customSearch(keyword.trim())
            } catch (e: Exception) {
                Log.e("RetrofitViewModel", "Response failed", e)
                errorMessage.value = "Search failed. Check API key, cx, Internet permission, or Logcat."
            } finally {
                isLoading.value = false
            }
        }
    }
}

kotlin

package com.example.googlesearchlab

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.viewModels
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.Button
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.OutlinedTextField
import androidx.compose.material3.Surface
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import com.example.googlesearchlab.ui.theme.GoogleSearchLabTheme

class MainActivity : ComponentActivity() {
    private val viewModel: RetrofitViewModel by viewModels()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        setContent {
            GoogleSearchLabTheme {
                Surface(
                    modifier = Modifier.fillMaxSize(),
                    color = MaterialTheme.colorScheme.background
                ) {
                    SearchResults(viewModel)
                }
            }
        }
    }
}

@Composable
fun SearchResults(viewModel: RetrofitViewModel) {
    val itemsReturned by viewModel.retrofitResponse
    val isLoading by viewModel.isLoading
    val errorMessage by viewModel.errorMessage
    var keyword by remember { mutableStateOf("") }

    Column(modifier = Modifier.padding(16.dp)) {
        Spacer(modifier = Modifier.height(32.dp))

        OutlinedTextField(
            value = keyword,
            onValueChange = { keyword = it },
            label = { Text("Keyword") },
            modifier = Modifier
                .fillMaxWidth()
                .padding(bottom = 8.dp),
            singleLine = true
        )

        Button(
            onClick = { viewModel.customSearch(keyword) },
            modifier = Modifier
                .fillMaxWidth()
                .height(48.dp),
            enabled = !isLoading
        ) {
            Text(if (isLoading) "Searching..." else "Search")
        }

        Spacer(modifier = Modifier.height(16.dp))

        when {
            errorMessage != null -> {
                Text(
                    text = errorMessage ?: "",
                    color = MaterialTheme.colorScheme.error,
                    modifier = Modifier.padding(top = 8.dp)
                )
            }

            itemsReturned.items.isNotEmpty() -> {
                val resultSnippet = itemsReturned.items[0].snippet
                Text(
                    text = "Results:$resultSnippet",
                    modifier = Modifier.padding(top = 8.dp)
                )
            }

            else -> {
                Text(
                    text = "No results yet",
                    modifier = Modifier.padding(top = 8.dp)
                )
            }
        }
    }
}

Lab Week 8 Summary

Overview

Goal

Lab Week 8 Summary

Overview

Goal

Task 0: 准备工作与安全提醒

Step 0.1：确认你使用的是个人 Gmail

Step 0.2：准备一个安全记录 key 的地方

Task 1: 获取 Google Custom Search API Key

Step 1.1：进入 Google Cloud Console 项目页面

Step 1.2：创建一个新的 Google Cloud Project

Step 1.3：进入 Enabled APIs & services

Step 1.4：打开 API Library

Step 1.5：启用 Custom Search API

Step 1.6：创建 API key

Step 1.7：如果忘记复制 API key，如何找回

Task 2: 获取 Search Engine ID，也就是 cx

Step 2.1：进入 Programmable Search Engine

Step 2.2：创建第一个 Search Engine

Step 2.3：进入 Customise / Control Panel

Step 2.4：可选：添加 Sites to Search

Task 3: 创建 Android 项目并添加 Retrofit 依赖和 Internet 权限

Step 3.1：创建新项目 GoogleSearchLab

Step 3.2：在 module-level Gradle 添加依赖

Step 3.3：处理 Android Studio 的黄色提示

Step 3.4：Sync Gradle

Step 3.5：添加 Internet permission

Task 4: 创建 Retrofit Model Classes

Step 4.1：理解 JSON 到 Kotlin object 的对应关系

Step 4.2：创建 SearchResponse.kt

Step 4.3：创建 Items.kt

Task 5: 创建 Retrofit Interface 和 Retrofit Object

Step 5.1：创建 RetrofitInterface.kt

Step 5.2：创建 RetrofitObject.kt

Task 6: 创建 Repository 和 ViewModel

Step 6.1：创建 ItemsRepository.kt

Step 6.2：创建 RetrofitViewModel.kt

Task 7: 编写 Compose UI 并运行 App

Step 7.1：替换或整理 MainActivity.kt

Step 7.2：检查最终文件结构

Step 7.3：运行 App

Step 7.4：用 Logcat 排查失败原因

Task 8: 可选验证：直接用浏览器或 curl 测试 API

Step 8.1：用浏览器测试 API URL

Step 8.2：用 curl 测试

Summary

本周必须理解的知识点

1. API key 和 cx 不是同一个东西

2. Retrofit 的 base URL 和 endpoint 会拼起来

3. @Query 对应 URL 问号后面的参数

4. 网络请求必须放在 coroutine 里

5. ViewModel 里的 state 变化会触发 Compose 更新

常见报错与排查

1. Unresolved reference: retrofit2

2. Suspend function should be called only from a coroutine

3. App 显示 Search failed

4. 返回结果为空，页面一直显示 No results yet

5. baseUrl must end in /

6. by、getValue、setValue 报错

关键概念对比

RetrofitInterface vs RetrofitObject

Repository vs ViewModel

remember vs ViewModel state

Room 示例和 Retrofit 示例的相同点

实验问题回答草稿

Q1: What is the purpose of Retrofit in this lab?

Q2: Why do we need model classes such as SearchResponse and Items?

Q3: Why is customSearch() a suspend function?

Q4: Why do we use a Repository?

Q5: Why do we add Internet permission to AndroidManifest.xml?

老师可能会问什么

1. 这次 App 发出的完整 API 请求长什么样？

2. @GET("customsearch/v1") 和 BASE_URL 是怎么组合的？

3. 为什么 UI 里不直接调用 Retrofit？

4. 如果 Google API 返回的 items 是空的会怎样？

5. 为什么要用 try / catch？

Step 4.2：创建 `SearchResponse.kt`

Step 4.3：创建 `Items.kt`

Step 5.1：创建 `RetrofitInterface.kt`

Step 5.2：创建 `RetrofitObject.kt`

Step 6.1：创建 `ItemsRepository.kt`

Step 6.2：创建 `RetrofitViewModel.kt`

Step 7.1：替换或整理 `MainActivity.kt`

3. `@Query` 对应 URL 问号后面的参数

1. `Unresolved reference: retrofit2`

2. `Suspend function should be called only from a coroutine`

5. `baseUrl must end in /`

6. `by`、`getValue`、`setValue` 报错

`remember` vs ViewModel state

Q2: Why do we need model classes such as `SearchResponse` and `Items`?

Q3: Why is `customSearch()` a suspend function?

Q5: Why do we add Internet permission to `AndroidManifest.xml`?

2. `@GET("customsearch/v1")` 和 `BASE_URL` 是怎么组合的？

4. 如果 Google API 返回的 `items` 是空的会怎样？

5. 为什么要用 `try / catch`？