Skip to content

9. 与服务器通信

RdvMedecins 服务器正在运行(见上一章,测试时其 [.env] 文件中设置 [CAPTCHA_TEST=test])。示例 22 到 25 从手机查询它。

9.0.1. 服务器在哪里?

由服务器自己提供的 Web 应用不必问这个问题:它的请求发往与页面相同的源。而移动应用则必须问:必须告诉它服务器的完整地址。然而,手机并不是运行服务器的那台电脑:

// =========================================================================
// common/Config.kt - JSON 服务器在哪里?(示例 22 到 25)
// -------------------------------------------------------------------------
// 由服务器自己提供的 Web 应用不必问
// 这个问题:它的请求发往与
// 页面相同的源。而移动应用则必须问:必须告诉它
// 服务器的完整地址。然而,手机并不是运行
// 服务器的那台电脑:
//   - 对手机(或模拟器)而言,“localhost”就是它自己。
//     命令  adb reverse tcp:8080 tcp:8080  解决了这个问题:它通过 USB 线
//     (对于模拟器则是直接)把手机的 8080 端口连接到电脑的 8080 端口。这是
//     默认选择的
//     方案:http://localhost:8080;
//   - Android 模拟器也可以通过特殊地址
//     10.0.2.2 看到这台电脑;
//   - 与电脑连接到同一个 Wi-Fi 网络的真实手机,可以
//     使用电脑在该网络上的地址(192.168.1.20 等)。
// 地址在编译时确定(BuildConfig,参见 app/build.gradle.kts):
//     gradlew installDebug -Pserver=http://10.0.2.2:8080
// =========================================================================
package fr.stahe.examples.common

import fr.stahe.examples.BuildConfig

object Config {
    val serverUrl: String = BuildConfig.SERVER_URL
}
  • 对手机(或模拟器)而言,“localhost”就是它自己。命令 [adb reverse tcp:8080 tcp:8080] 通过 USB 线(对于模拟器则是直接)把手机上的 8080 端口连接到电脑上的 8080 端口。这是默认的解决方案:[http://localhost:8080]。每次启动模拟器时都必须重新执行该命令;
  • 模拟器也可以通过特殊地址 [10.0.2.2] 看到这台电脑;
  • 与电脑连接到同一个 Wi-Fi 网络的真实手机,可以使用电脑在该网络上的地址([192.168.1.20] 等),前提是电脑的防火墙允许 8080 端口的流量通过。

该地址是 [BuildConfig] 类的一个字段,在编译时生成(见 [app/build.gradle.kts],示例 01);它可以在不修改代码的情况下更改:

gradlew installDebug -Pserver=http://10.0.2.2:8080

最后,清单申请权限 [INTERNET],并允许“未加密”的 HTTP 流量([usesCleartextTraffic]):从 [Android] 9 开始,默认只允许 HTTPS。

9.1. 示例 22:第一个 HTTP 请求

向服务器请求一个验证码:[GET /api/captcha] 返回 [{ "id": "...", "svg": "<svg ...>" }]。HTTP 客户端是 [OkHttp],它是 [Android] 上最常用的客户端(相当于 [Flutter] 的 [http] 包)。

// =========================================================================
// ex22/Ex22Activity.kt - 向服务器发出的第一个 HTTP 请求
// -------------------------------------------------------------------------
// RdvMedecins JSON 服务器必须正在运行(端口 8080)。我们向它请求
// 一个验证码:GET /api/captcha -> { "id": "...", "svg": "<svg ...>" }。
//
//   - OkHttp,Android 上最常用的 HTTP 客户端:我们描述
//     请求(Request),客户端执行它(newCall(...).execute())并
//     返回响应:它的状态码(code)、它的头
//     (headers)、它的响应体(body);
//   - execute() 会阻塞直到收到响应:Android 禁止在
//     屏幕的线程上调用它。withContext(Dispatchers.IO)
//     在另一个线程上执行它,而协程等待结果;
//   - Json.parseToJsonElement(text):JSON 响应体 -> Kotlin 对象;
//   - 服务器的地址取决于应用在哪里运行
//     (模拟器、手机等):参见 common/Config.kt;
//   - 要显示的三种状态:加载中、成功、出错;
//   - 验证码图像是 SVG:参见 common/SvgImage.kt。
// =========================================================================
package fr.stahe.examples.ex22

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.foundation.border
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.material3.Button
import androidx.compose.material3.Card
import androidx.compose.material3.CardDefaults
import androidx.compose.material3.LinearProgressIndicator
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableIntStateOf
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.font.FontFamily
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp
import fr.stahe.examples.common.Config
import fr.stahe.examples.common.SvgImage
import fr.stahe.examples.common.ExamplePage
import fr.stahe.examples.common.ExamplesTheme
import kotlinx.coroutines.CancellationException
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext
import kotlinx.serialization.json.Json
import kotlinx.serialization.json.jsonObject
import kotlinx.serialization.json.jsonPrimitive
import okhttp3.OkHttpClient
import okhttp3.Request

// GET /api/captcha 返回的内容
data class Captcha(val id: String, val svg: String)

// 一个 HTTP 客户端:创建开销很大的对象,因此只创建一次
val client = OkHttpClient()

// 请求:一个挂起函数,返回验证码或抛出异常
suspend fun readCaptcha(): Captcha = withContext(Dispatchers.IO) {
    val request = Request.Builder().url("${Config.serverUrl}/api/captcha").build()
    client.newCall(request).execute().use { response ->
        // OkHttp 对错误响应(4xx、5xx)不会抛出异常:
        // 要自己检测状态码
        if (!response.isSuccessful) {
            throw Exception("the server responded ${response.code} ${response.message}")
        }
        val json = Json.parseToJsonElement(response.body!!.string()).jsonObject
        Captcha(json["id"]!!.jsonPrimitive.content, json["svg"]!!.jsonPrimitive.content)
    }
}

class Ex22Activity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        enableEdgeToEdge()
        setContent { ExamplesTheme { CaptchaPage() } }
    }
}

@Composable
fun CaptchaPage() {
    var captcha by remember { mutableStateOf<Captcha?>(null) }
    var loading by remember { mutableStateOf(true) }
    var error by remember { mutableStateOf<String?>(null) }
    var requestCount by remember { mutableIntStateOf(0) }
    // 请求编号:更改它会重新启动下面的副作用
    var demand by remember { mutableIntStateOf(0) }

    // 屏幕一出现就发出请求(demand = 0),然后在每次
    // 新的请求编号出现时再发。如果在上一个请求得到响应之前
    // 又来了新的请求,上一个协程会被取消:
    // 它那个已经过期的响应永远不会被显示
    LaunchedEffect(demand) {
        loading = true
        error = null
        try {
            captcha = readCaptcha()
            requestCount++
        } catch (e: CancellationException) {
            throw e // 协程已被取消(新的请求):没有可显示的内容
        } catch (e: Exception) {
            // 根本没有响应(服务器已停止、地址错误等),或错误
            error = e.message ?: e.toString()
            captcha = null
        }
        loading = false
    }

    ExamplePage("Example 22 - a first HTTP request") {
        Text("Server: ${Config.serverUrl}", color = Color.Gray)
        Spacer(Modifier.height(12.dp))
        if (loading) LinearProgressIndicator(Modifier.fillMaxWidth())
        error?.let {
            Card(colors = CardDefaults.cardColors(containerColor = Color(0xFFFFEBEE))) {
                Text("Unable to get a captcha: $it.\nIs the RdvMedecins JSON server running (port 8080)?", Modifier.padding(12.dp))
            }
        }
        val c = captcha
        if (c != null && !loading) {
            SvgImage(
                c.svg,
                height = 60.dp,
                modifier = Modifier.border(1.dp, Color(0xFFE0E0E0), RoundedCornerShape(6.dp)).padding(4.dp),
            )
            Spacer(Modifier.height(8.dp))
            Text("id: ${c.id}", fontFamily = FontFamily.Monospace, fontSize = 11.sp)
        }
        Spacer(Modifier.height(12.dp))
        Button(onClick = { demand++ }, enabled = !loading) { Text("Another image") }
        Spacer(Modifier.height(8.dp))
        Text("$requestCount successful request(s)", color = Color.Gray)
    }
}
  • 第 66 行:一个 HTTP 客户端,创建开销很大的对象,因此只创建一次;
  • 第 69–71 行:请求,一个挂起函数。请求([Request])被描述出来;客户端执行它([newCall(...).execute()])并返回响应:它的状态码、头和响应体。[execute()] 会阻塞直到收到响应:[Android] 禁止在屏幕的执行线程上调用它([NetworkOnMainThreadException])。[withContext(Dispatchers.IO)] 在专为 I/O 保留的线程上执行它,而协程则等待结果;
  • 第 74–75 行:[OkHttp] 对错误响应(4xx、5xx)不会抛出异常;相反,我们检查状态码。不过,如果根本没有响应(服务器宕机、地址不正确),它会抛出 [IOException];
  • 第 77–78 行:JSON 响应体,“手动”读取:[jsonObject]、[jsonPrimitive.content];
  • 第 103–116 行:请求由一个 [LaunchedEffect] 触发,其键是请求编号:“Another image”按钮使它递增,从而重新启动该副作用。如果在上一个请求得到响应之前又发出了新请求,上一个协程会被取消:它的响应此时已经过期,永远不会被显示;
  • 第 122–136 行:要显示的三种状态:进行中(进度条)、错误和成功。

验证码图像是 SVG 格式,[Android] 本身无法显示它:由 [AndroidSVG] 库把它渲染成图像([Bitmap]):

// =========================================================================
// common/SvgImage.kt - 绘制以文本形式给出的 SVG 图像
// -------------------------------------------------------------------------
// 验证码图像由服务器生成,采用 SVG 格式(一段描述
// 图形的文本)。Android 本身无法显示它:由
// AndroidSVG 库把它绘制成图像(Bitmap),
// 再由 Compose 用 Image 组件显示。
// =========================================================================
package fr.stahe.examples.common

import android.graphics.Bitmap
import android.graphics.Canvas
import androidx.compose.foundation.Image
import androidx.compose.foundation.layout.height
import androidx.compose.runtime.Composable
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.asImageBitmap
import androidx.compose.ui.layout.ContentScale
import androidx.compose.ui.unit.Dp
import androidx.compose.ui.unit.dp
import com.caverock.androidsvg.SVG

@Composable
fun SvgImage(svg: String, modifier: Modifier = Modifier, height: Dp = 50.dp, description: String? = null) {
    // 只有当 SVG 文本变化时才会重新绘制(remember(svg))
    val image = remember(svg) {
        val document = SVG.getFromString(svg)
        // 绘制成“自然”尺寸的 3 倍大:得到清晰的图像
        val scale = 3f
        val width = (document.documentWidth.takeIf { it > 0 } ?: 150f)
        val tall = (document.documentHeight.takeIf { it > 0 } ?: 50f)
        val bitmap = Bitmap.createBitmap((width * scale).toInt(), (tall * scale).toInt(), Bitmap.Config.ARGB_8888)
        val canvas = Canvas(bitmap)
        canvas.scale(scale, scale)
        document.renderToCanvas(canvas)
        bitmap.asImageBitmap()
    }
    Image(image, contentDescription = description, contentScale = ContentScale.Fit, modifier = modifier.height(height))
}

Image

Image

停止服务器,然后点击“Another image”:会显示错误。

9.2. 示例 23:登录、Cookie 和会话

服务器把 JWT 令牌放在一个 Cookie 中。在浏览器中,由浏览器负责存储 Cookie 并把它们发回;应用代码什么都不需要做。在手机上没有浏览器:必须由应用来处理这件事。[OkHttp] 可以做到这一点,只要给它提供一个“Cookie 罐”([CookieJar]):

// =========================================================================
// common/HttpClient.kt - 一个处理 Cookie 的 HTTP 客户端
// -------------------------------------------------------------------------
// RdvMedecins 服务器把 JWT 令牌放在一个 Cookie 中(httpOnly)。
// 在浏览器中,由浏览器存储 Cookie,并在每个请求中
// 把它们发回:应用的代码无事可做。
// 在手机上没有浏览器:必须由应用
// 来扮演它的角色,也就是:
//   1. 读取每个响应的“Set-Cookie”头,并存储 Cookie;
//   2. 在每个请求的“Cookie”头中把它们发回。
// 只要给 OkHttp 库一个 CookieJar
// (“Cookie 罐”),它就会替我们完成:这是一个有两个函数的类,saveFromResponse
// (存入)和 loadForRequest(取出)。这个类还会把 Cookie 存储
// 在设备上(SharedPreferences):停止后
// 重新启动应用,我们仍然保持登录状态。
// =========================================================================
package fr.stahe.examples.common

import android.content.Context
import android.content.SharedPreferences
import androidx.core.content.edit
import okhttp3.Cookie
import okhttp3.CookieJar
import okhttp3.HttpUrl
import okhttp3.HttpUrl.Companion.toHttpUrl
import okhttp3.OkHttpClient
import java.util.concurrent.TimeUnit

class DeviceCookieJar(private val storage: SharedPreferences) : CookieJar {
    // Cookie 名称 -> Cookie(它的值、域、过期时间等)
    private val cookies = mutableMapOf<String, Cookie>()

    init {
        // 上一次使用期间存储的 Cookie:每一个
        // 都以其 Set-Cookie 头的形式存储
        val base = Config.serverUrl.toHttpUrl()
        for (text in storage.getStringSet(KEY, emptySet()).orEmpty()) {
            Cookie.parse(base, text)?.let { cookies[it.name] = it }
        }
    }

    // 响应带来了 Cookie:我们存储它们。已经过期的 Cookie
    // (退出登录:服务器就是这样删除它的)会被移除
    @Synchronized
    override fun saveFromResponse(url: HttpUrl, cookies: List<Cookie>) {
        for (c in cookies) {
            if (c.expiresAt < System.currentTimeMillis() || c.value.isEmpty()) {
                this.cookies.remove(c.name)
            } else {
                this.cookies[c.name] = c
            }
        }
        storage.edit { putStringSet(KEY, this@DeviceCookieJar.cookies.values.map { it.toString() }.toSet()) }
    }

    // 请求发出:取出与它相关的 Cookie(地址、路径),且未过期
    @Synchronized
    override fun loadForRequest(url: HttpUrl): List<Cookie> =
        cookies.values.filter { it.expiresAt >= System.currentTimeMillis() && it.matches(url) }

    companion object {
        private const val KEY = "rdvmedecins.cookies"
    }
}

// 示例的 HTTP 客户端:整个应用只有一个
fun createHttpClient(context: Context): OkHttpClient = OkHttpClient.Builder()
    .cookieJar(DeviceCookieJar(context.getSharedPreferences("examples", Context.MODE_PRIVATE)))
    // 10 秒后仍无响应:请求失败
    .connectTimeout(10, TimeUnit.SECONDS)
    .readTimeout(10, TimeUnit.SECONDS)
    .build()
  • 第 29 行:[CookieJar] 有两个函数:[saveFromResponse](存储响应中的 Cookie)和 [loadForRequest](取出用于请求的 Cookie);
  • 第 33–38 行:启动时,在上一次会话期间存储的 Cookie(保存在设备上,[SharedPreferences],一个小型键值文件;见示例 20)以其 [Set-Cookie] 头的形式被取回;
  • 第 44–53 行:已经过期或为空的 Cookie 会被移除;服务器就是这样在退出登录时删除 Cookie 的;[@Synchronized]:[OkHttp] 可能同时从多个线程调用这些函数;
  • 第 67–72 行:示例中的 HTTP 客户端,带有它的 Cookie 罐和超时设置。

客户端在整个应用中只创建一次,位于 [Application] 对象内(在清单中声明),[Android] 会在启动时、任何 Activity 开始之前创建它:

// =========================================================================
// ExamplesApplication.kt - “应用”对象
// -------------------------------------------------------------------------
// Android 在应用启动时、任何 Activity 之前创建一个 Application 对象,并一直
// 保留到应用停止(它在
// AndroidManifest.xml 中声明,android:name=".ExamplesApplication")。它是
// 存放所有 Activity 都要共享的东西的地方:
// 这里是 HTTP 客户端及其 Cookie 罐(示例 23 到 25)。
// Activity 通过 (application as ExamplesApplication).api 获取它。
// =========================================================================
package fr.stahe.examples

import android.app.Application
import fr.stahe.examples.common.Api
import fr.stahe.examples.common.createHttpClient
import okhttp3.OkHttpClient

class ExamplesApplication : Application() {
    // by lazy:在首次请求时创建
    val httpClient: OkHttpClient by lazy { createHttpClient(this) }
    val api: Api by lazy { Api(httpClient) }
}

异步操作(登录、保存等)有一个必须由屏幕显示的状态:它正在进行吗?它是否以错误结束?一个小类负责处理这件事:

// =========================================================================
// ex23/Command.kt - 一个动作、它的状态、它的结果
// -------------------------------------------------------------------------
// 异步动作(登录、保存等)有一个屏幕必须显示的状态:
// 它是否正在进行(按钮被禁用)?它是否
// 以错误(消息)结束?这就是“Command”模式,精简到
// 最核心的部分:
//
//     val loginCommand = remember { Command() }
//     scope.launch { loginCommand.execute { logIn() } }    // 启动该动作
//     loginCommand.inProgress, loginCommand.error          // 它的状态
//
// 它的两个属性是被 Compose 观察的状态:动作开始和结束时
// 屏幕都会重绘。
// =========================================================================
package fr.stahe.examples.ex23

import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.setValue
import kotlinx.coroutines.CancellationException

class Command {
    var inProgress by mutableStateOf(false)
        private set
    var error by mutableStateOf<String?>(null)
        private set

    // 执行该动作,如果另一个动作尚未在进行中
    suspend fun execute(action: suspend () -> Unit) {
        if (inProgress) return // 禁止重复提交(双击按钮)
        inProgress = true
        error = null
        try {
            action()
        } catch (e: CancellationException) {
            throw e // 被取消的协程必须保持被取消的状态
        } catch (e: Exception) {
            error = e.message ?: e.toString() // 错误被保留,以便显示
        } finally {
            // finally:在所有情况下都会执行,无论成功还是出错
            inProgress = false
        }
    }

    fun clearError() {
        error = null
    }
}
  • 第 31 行:防止重复提交(双击按钮);
  • 第 40–42 行:[finally]:在所有情况下都会执行,无论成功还是出错。

登录屏幕:

// =========================================================================
// ex23/Ex23Activity.kt - 登录 RdvMedecins 服务器
// -------------------------------------------------------------------------
//   1. 启动时:GET /api/auth/me - 我们是否已经登录?
//      (应用可能已被停止;服务器则会读取
//      呈递给它的 Cookie);
//   2. 登录:POST /api/auth/login,JSON 请求体 { login, password,
//      captchaId, captcha }。成功时,服务器发送 JWT 令牌的
//      Cookie(Set-Cookie 头);
//   3. 受保护的请求:GET /api/doctors。Cookie 随请求一起发送;
//   4. 退出登录:POST /api/auth/logout - 服务器删除 Cookie。
// 存储 Cookie 并把它发回的,是应用的 HTTP 客户端(common/HttpClient.kt),
// 即带有 Cookie 罐的那个。
// =========================================================================
package fr.stahe.examples.ex23

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.Spacer
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.Card
import androidx.compose.material3.CardDefaults
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.OutlinedButton
import androidx.compose.material3.OutlinedTextField
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.runtime.setValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.SpanStyle
import androidx.compose.ui.text.buildAnnotatedString
import androidx.compose.ui.text.font.FontWeight
import androidx.compose.ui.text.input.PasswordVisualTransformation
import androidx.compose.ui.text.withStyle
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp
import fr.stahe.examples.ExamplesApplication
import fr.stahe.examples.common.Config
import fr.stahe.examples.common.SvgImage
import fr.stahe.examples.common.ExamplePage
import fr.stahe.examples.common.ExamplesTheme
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch
import kotlinx.coroutines.withContext
import kotlinx.serialization.json.Json
import kotlinx.serialization.json.JsonArray
import kotlinx.serialization.json.JsonElement
import kotlinx.serialization.json.JsonObject
import kotlinx.serialization.json.buildJsonObject
import kotlinx.serialization.json.jsonArray
import kotlinx.serialization.json.jsonObject
import kotlinx.serialization.json.jsonPrimitive
import kotlinx.serialization.json.put
import okhttp3.MediaType.Companion.toMediaType
import okhttp3.OkHttpClient
import okhttp3.Request
import okhttp3.RequestBody.Companion.toRequestBody

// 本示例需要的少量消息(示例 25 将使用字典)
val messages = mapOf(
    "LOGIN.ERROR" to "Incorrect login or password.",
    "ERRORS.WRONG_CAPTCHA" to "The characters do not match the image.",
    "ERRORS.TOO_MANY_ATTEMPTS" to "Too many failed attempts. Try again later.",
)

// 非 2xx 的响应会变成一个异常,它保留自己的状态码和响应体
class ErrorResponse(val code: Int, val body: String) : Exception("the server responded $code")

// 一个只保留我们所关心内容的 HTTP 响应
data class Response(val code: Int, val body: String)

class Ex23Activity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        enableEdgeToEdge()
        // 应用的 HTTP 客户端,带有它的 Cookie 罐
        val client = (application as ExamplesApplication).httpClient
        setContent { ExamplesTheme { LoginPage(client) } }
    }
}

// 在输入输出线程上执行请求
suspend fun send(client: OkHttpClient, request: Request): Response = withContext(Dispatchers.IO) {
    client.newCall(request).execute().use { Response(it.code, it.body?.string().orEmpty()) }
}

@Composable
fun LoginPage(client: OkHttpClient) {
    var user by remember { mutableStateOf<JsonObject?>(null) } // null:没有人登录
    var doctors by remember { mutableStateOf<JsonArray?>(null) }
    var captcha by remember { mutableStateOf<JsonObject?>(null) }
    var ready by remember { mutableStateOf(false) } // 初始检查是否已完成?
    var serverError by remember { mutableStateOf<String?>(null) }
    val loginCommand = remember { Command() }
    var login by remember { mutableStateOf("admin") }
    var password by remember { mutableStateOf("") }
    var captchaAnswer by remember { mutableStateOf("") }
    val scope = rememberCoroutineScope()

    fun url(path: String) = "${Config.serverUrl}/api$path"

    // 一个我们想要其 JSON 响应体的 GET 请求;如果不是 2xx 则抛出异常
    suspend fun read(path: String): JsonElement {
        val r = send(client, Request.Builder().url(url(path)).build())
        if (r.code >= 300) throw ErrorResponse(r.code, r.body)
        return Json.parseToJsonElement(r.body)
    }

    // 一个带 JSON 请求体的 POST
    suspend fun post(path: String, body: JsonObject): Response =
        send(client, Request.Builder().url(url(path)).post(body.toString().toRequestBody("application/json".toMediaType())).build())

    suspend fun loadCaptcha() {
        captcha = read("/captcha").jsonObject
        captchaAnswer = ""
    }

    suspend fun loadDoctors() {
        doctors = read("/doctors").jsonArray
    }

    // 1. 谁已登录?200 -> 该用户;401 -> 没有人
    LaunchedEffect(Unit) {
        try {
            user = read("/auth/me").jsonObject
            loadDoctors()
        } catch (e: ErrorResponse) {
            // “catch (e: Type)”:只捕获这种类型的异常
            if (e.code == 401) loadCaptcha() else serverError = "The server responded ${e.code}."
        } catch (e: java.io.IOException) {
            serverError = "Is the RdvMedecins JSON server running (${Config.serverUrl})?"
        }
        ready = true
    }

    // 2. 登录:由 Command 执行的动作,它会记住自己的错误
    suspend fun logIn() {
        val r = post(
            "/auth/login",
            buildJsonObject {
                put("login", login.trim())
                put("password", password)
                put("captchaId", captcha?.get("id")?.jsonPrimitive?.content)
                put("captcha", captchaAnswer)
            },
        )
        if (r.code != 200) {
            // 错误响应的 JSON 响应体:{ statusCode, key, ... }
            val key = Json.parseToJsonElement(r.body).jsonObject["key"]!!.jsonPrimitive.content
            loadCaptcha() // 每张图像只使用一次
            throw Exception("${r.code} - ${messages[key] ?: key}")
        }
        password = ""
        user = Json.parseToJsonElement(r.body).jsonObject
        loadDoctors()
    }

    // 4. 退出登录
    suspend fun logOut() {
        post("/auth/logout", JsonObject(emptyMap()))
        user = null
        doctors = null
        loadCaptcha()
    }

    // 一段 JSON 文本 -> 它的值,不带引号
    fun JsonObject.text(key: String) = this[key]?.jsonPrimitive?.content.orEmpty()

    ExamplePage("Example 23 - logging in to the server") {
        val u = user
        when {
            !ready -> Text("Checking the session...", color = Color.Gray)
            // 已登录
            u != null -> Card(Modifier.fillMaxWidth()) {
                Column(Modifier.padding(12.dp)) {
                    Text(
                        buildAnnotatedString {
                            append("Logged in: ")
                            withStyle(SpanStyle(fontWeight = FontWeight.Bold)) { append(u.text("name")) }
                            append(" (${u.text("login")}), role ${u.text("role")}")
                        },
                    )
                    Spacer(Modifier.height(8.dp))
                    Text("GET /api/doctors", style = MaterialTheme.typography.titleSmall)
                    for (d in doctors.orEmpty()) {
                        val o = d.jsonObject
                        Text("• ${o.text("title")} ${o.text("firstName")} ${o.text("lastName")}")
                    }
                    Spacer(Modifier.height(8.dp))
                    Text("Stop then restart the application: you stay logged in.", color = Color.Gray)
                    Spacer(Modifier.height(8.dp))
                    OutlinedButton(onClick = { scope.launch { logOut() } }) { Text("Log out") }
                }
            }
            // 未登录:显示表单
            serverError == null -> Card(Modifier.fillMaxWidth()) {
                Column(Modifier.padding(12.dp)) {
                    OutlinedTextField(login, { login = it }, label = { Text("Login") }, singleLine = true, modifier = Modifier.fillMaxWidth())
                    OutlinedTextField(
                        password,
                        { password = it },
                        label = { Text("Password") },
                        singleLine = true,
                        visualTransformation = PasswordVisualTransformation(),
                        modifier = Modifier.fillMaxWidth(),
                    )
                    Spacer(Modifier.height(12.dp))
                    Row(verticalAlignment = Alignment.CenterVertically) {
                        captcha?.let { SvgImage(it.text("svg"), height = 50.dp) }
                        TextButton(onClick = { scope.launch { runCatching { loadCaptcha() } } }) { Text("Another image") }
                    }
                    OutlinedTextField(
                        captchaAnswer,
                        { captchaAnswer = it },
                        label = { Text("Copy the characters of the image") },
                        singleLine = true,
                        modifier = Modifier.fillMaxWidth(),
                    )
                    Spacer(Modifier.height(16.dp))
                    // 这一部分跟随该命令的状态
                    Button(onClick = { scope.launch { loginCommand.execute { logIn() } } }, enabled = !loginCommand.inProgress) {
                        Text(if (loginCommand.inProgress) "Logging in..." else "Log in")
                    }
                    loginCommand.error?.let { Text(it, color = Color.Red, modifier = Modifier.padding(top = 12.dp)) }
                    Spacer(Modifier.height(8.dp))
                    Text("Accounts: admin, pelissier, martin... (password = login).", color = Color.Gray, fontSize = 12.sp)
                }
            }
        }
        serverError?.let {
            Card(colors = CardDefaults.cardColors(containerColor = Color(0xFFFFEBEE))) { Text(it, Modifier.padding(12.dp)) }
        }
    }
}
  • 第 92 行:应用的 HTTP 客户端([application as ExamplesApplication]:一次类型转换);
  • 第 138–148 行:启动时执行 [GET /api/auth/me]:我们是否已经登录?应用可能已被关闭;但 Cookie 仍保留在设备上。[catch (e: ErrorResponse)] 只捕获这种类型的异常;401 表示“未授权”;
  • 第 152–170 行:[POST /api/auth/login],由 [buildJsonObject] 生成的 JSON 请求体。如果尝试失败,响应体会提供错误代码;随后会请求一个新的验证码(每张图像只使用一次);
  • 第 174–178 行:退出登录,[POST /api/auth/logout]:服务器删除 Cookie;
  • 第 182 行:一个局部扩展函数,用于从 JSON 对象中读取文本;
  • 第 236–239 行:按钮跟踪该命令的状态。

Image

Image

Image

停止应用(从最近使用的应用列表中将其移除),然后重新启动该示例:你仍然处于登录状态。

9.3. 示例 24:API 访问层

示例 23 为每个请求重复相同的步骤:服务器地址、[/api] 前缀、JSON 请求体、状态码检查,以及读取错误响应体。这些内容被归并为三层。第一层执行请求,并把任何错误转换为单一的异常类:

// =========================================================================
// common/ApiError.kt - 所有 API 错误共用一个类
// -------------------------------------------------------------------------
// RdvMedecins 服务器的所有错误响应都有相同的形状:
//   { "statusCode": 409, "key": "ERRORS.LOGIN_TAKEN", "params": {...}, "fields": {...} }
// 但请求也可能以其他方式失败:根本没有响应
// (网络中断、服务器已停止、地址错误),或者收到的响应
// 并非来自我们的服务器(来自代理的错误页面)。我们把
// 所有这些都转换成一个异常类 ApiError,它携带服务器发送的
// 翻译键(以及参数,如果有的话,还有
// 每个字段的错误)。
// =========================================================================
package fr.stahe.examples.common

import kotlinx.serialization.json.Json
import kotlinx.serialization.json.JsonObject
import kotlinx.serialization.json.JsonPrimitive
import kotlinx.serialization.json.jsonObject

class ApiError(
    val statusCode: Int, // 0:服务器没有响应
    val key: String, // 例如:"ERRORS.LOGIN_TAKEN"
    val params: Map<String, String> = emptyMap(),
    val fields: Map<String, String> = emptyMap(),
) : Exception("$statusCode $key") {

    override fun toString() = "$statusCode $key"

    // companion object:属于类本身的内容(相当于 Java 的“static”)
    companion object {
        // 错误响应(4xx、5xx)-> 一个 ApiError
        fun fromResponse(statusCode: Int, body: String): ApiError {
            // runCatching:得到结果,如果响应体不是 JSON 则得到 null
            // (此时响应的就不是我们的服务器)
            val json = runCatching { Json.parseToJsonElement(body).jsonObject }.getOrNull()
            val key = (json?.get("key") as? JsonPrimitive)?.content
            if (json == null || key == null) {
                return ApiError(statusCode, if (statusCode >= 500) "ERRORS.SERVER_UNREACHABLE" else "ERRORS.SERVER_ERROR")
            }
            return ApiError(statusCode, key, strings(json["params"]), strings(json["fields"]))
        }

        // 一个 JSON 对象 { "name": "ERRORS..." } -> Map<String, String>(否则为空)
        private fun strings(json: Any?): Map<String, String> =
            (json as? JsonObject)?.mapValues { (_, v) -> (v as? JsonPrimitive)?.content ?: v.toString() } ?: emptyMap()
    }
}
// =========================================================================
// common/Api.kt - 一行代码发出 API 请求
// -------------------------------------------------------------------------
// 在示例 23 中,每个请求都重复相同的步骤:服务器
// 地址、/api 前缀、JSON 请求体、状态码检查、读取
// 错误响应体等。它们在这里被归并在一起:
//
//   val json = api.get("/doctors")
//   api.post("/appointments", buildJsonObject { put("day", day); put("slotId", 3) })
//
//   - 成功时,函数返回 JSON 响应体(一个 JsonElement:
//     对象、数组等),响应体为空则返回 null;
//   - 失败时,它抛出 ApiError。
// 它们是挂起函数:它们等待服务器的响应
// 而不阻塞手机。请求本身在为输入输出
// 保留的线程上执行(Dispatchers.IO):Android
// 禁止在屏幕的线程上访问网络。
// 所有请求都经过 request 函数:这里是处理
// 它们共有的问题的地方(参见案例研究和
// 401 响应)。供示例 24 和 25 使用。
// =========================================================================
package fr.stahe.examples.common

import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext
import kotlinx.serialization.json.Json
import kotlinx.serialization.json.JsonElement
import kotlinx.serialization.json.JsonObject
import okhttp3.MediaType.Companion.toMediaType
import okhttp3.OkHttpClient
import okhttp3.Request
import okhttp3.RequestBody.Companion.toRequestBody
import java.io.IOException

class Api(private val client: OkHttpClient) {

    suspend fun request(method: String, url: String, body: JsonElement? = null): JsonElement? =
        withContext(Dispatchers.IO) {
            // 一个 JSON 请求体(服务器会拒绝没有它的 POST)
            val httpBody = body?.toString()?.toRequestBody("application/json".toMediaType())
            val request = Request.Builder().url("${Config.serverUrl}/api$url").method(method, httpBody).build()
            try {
                // use:响应在代码块结束时被关闭(释放)
                client.newCall(request).execute().use { response ->
                    val text = response.body?.string().orEmpty()
                    if (!response.isSuccessful) throw ApiError.fromResponse(response.code, text)
                    if (text.isEmpty()) null else Json.parseToJsonElement(text)
                }
            } catch (e: IOException) {
                // 没有响应(网络、服务器已停止、地址错误)
                throw ApiError(0, "ERRORS.SERVER_UNREACHABLE")
            }
        }

    suspend fun get(url: String) = request("GET", url)

    // POST 总是带有 JSON 请求体:默认为 {}
    suspend fun post(url: String, body: JsonElement = JsonObject(emptyMap())) = request("POST", url, body)

    suspend fun put(url: String, body: JsonElement) = request("PUT", url, body)

    suspend fun delete(url: String, body: JsonElement? = null) = request("DELETE", url, body)
}
  • 第 37–47 行:如果成功,函数返回 JSON 响应体([JsonElement]),响应体为空则返回 [null];如果不成功,则抛出 [ApiError];
  • 第 55–62 行:按 HTTP 方法提供的快捷函数。

交换的 JSON 对象变成 [Kotlin] 和 [@Serializable] 类:

// =========================================================================
// common/Types.kt - 与 RdvMedecins API 交换的 JSON 对象
// (参见关于黑盒的章节,其中描述了每个路由)
// -------------------------------------------------------------------------
// 每个类都是 @Serializable:kotlinx.serialization 插件为它编写
// 从 JSON 构建它的代码。读取时会检查收到的 JSON 的
// 形状:缺少字段或字段类型错误会在接收时就抛出
// 异常,而不是稍后在显示过程中才出错。
//     val u = json.decodeFromJsonElement<User>(response)
// 可选字段有默认值(login: String? = null)。
// =========================================================================
package fr.stahe.examples.common

import kotlinx.serialization.Serializable
import kotlinx.serialization.json.Json
import kotlinx.serialization.json.JsonElement
import kotlinx.serialization.serializer

enum class Role { ADMIN, DOCTOR, USER }

// POST /api/auth/login、GET /api/auth/me
@Serializable
data class User(val login: String, val name: String, val role: Role)

// GET /api/captcha
@Serializable
data class Captcha(val id: String, val svg: String)

// 一位医生或一位客户(GET /api/doctors、GET /api/clients 等)
@Serializable
data class Person(
    val id: Int,
    val version: Int,
    val title: String,
    val firstName: String,
    val lastName: String,
    val login: String? = null, // 仅限 ADMIN
) {
    val fullName get() = "$title $firstName $lastName"
}

// 一个人的姓名,别无其他
@Serializable
data class Identity(val title: String, val firstName: String, val lastName: String) {
    override fun toString() = "$title $firstName $lastName"
}

// GET /api/schedule 的一行
@Serializable
data class ScheduleSlot(
    val id: Int,
    val startHour: Int,
    val startMinute: Int,
    val endHour: Int,
    val endMinute: Int,
    val free: Boolean,
    val patient: Identity?,
    val mine: Boolean,
    val bookable: Boolean,
    val appointmentId: Int?,
) {
    // “8:00 - 8:20”
    val timeRange: String
        get() {
            fun hm(h: Int, m: Int) = "$h:${m.toString().padStart(2, '0')}"
            return "${hm(startHour, startMinute)} - ${hm(endHour, endMinute)}"
        }
}

// GET /api/schedule?doctorId=...&day=...
@Serializable
data class Schedule(val doctor: Person, val day: String, val slots: List<ScheduleSlot>, val info: String?)

// JSON 读取器:ignoreUnknownKeys,客户端不使用的字段
// 会被忽略(服务器可以添加字段而不会破坏客户端)
val apiJson = Json { ignoreUnknownKeys = true }

// JsonElement -> Kotlin 对象:一个“具体化”的泛型函数(类型 T
// 在运行时已知);serializer<T>():插件编写的代码
inline fun <reified T> JsonElement?.read(): T =
    apiJson.decodeFromJsonElement(serializer<T>(), this ?: throw IllegalStateException("empty response"))
  • 第 37 行:可选字段有默认值;[Identity?]:一个对象,或 [null];
  • 第 76 行:[ignoreUnknownKeys]:客户端没有用到的字段会被忽略(服务器可以添加它们而不会破坏客户端);
  • 第 80–81 行:一个泛型扩展函数是“具体化”的([reified]:类型 [T] 在运行时已知,这由 [inline] 允许)。[serializer<T>()]:插件为 [T] 编写的代码。读取时会检查 JSON 的格式:缺少字段或字段类型错误会在接收时就抛出异常,而不是稍后在显示过程中才出错。

第二层:为 API 的每个路由提供一个类型安全的函数。屏幕不再认识 URL、[OkHttp] 或 JSON。这相当于服务器端 DAO 层在客户端的对应物;在 [Android] 架构指南中,称为“仓库”:

// =========================================================================
// ex24/RdvMedecins.kt - API 访问层
// -------------------------------------------------------------------------
// API 的每个路由对应一个类型化的函数。屏幕既不知道
// URL,也不知道 OkHttp,更不知道 JSON 格式:它们调用返回
// Kotlin 对象(Person、Schedule 等)的函数。
// 这相当于服务器端 DAO 层在客户端的对应物:如果 API
// 变化(URL、字段名称),只需修改这个文件。在
// Android 架构指南中,它被称为“仓库”。
// =========================================================================
package fr.stahe.examples.ex24

import android.net.Uri
import fr.stahe.examples.common.Schedule
import fr.stahe.examples.common.Api
import fr.stahe.examples.common.Person
import fr.stahe.examples.common.read
import kotlinx.serialization.json.buildJsonObject
import kotlinx.serialization.json.put

class RdvMedecins(private val api: Api) {
    suspend fun getDoctors(): List<Person> = api.get("/doctors").read()

    suspend fun getClients(): List<Person> = api.get("/clients").read()

    // Uri.Builder 构造“doctorId=1&day=2030-01-15”,并对需要编码的内容进行编码
    suspend fun getSchedule(doctorId: Int, day: String): Schedule {
        val params = Uri.Builder()
            .appendQueryParameter("doctorId", "$doctorId")
            .appendQueryParameter("day", day)
            .build().encodedQuery
        return api.get("/schedule?$params").read()
    }

    // clientId:可选;只有当它不为 null 时,这个键才会放入 JSON 中
    suspend fun book(day: String, slotId: Int, clientId: Int? = null) {
        api.post(
            "/appointments",
            buildJsonObject {
                put("day", day)
                put("slotId", slotId)
                if (clientId != null) put("clientId", clientId)
            },
        )
    }

    suspend fun cancelAppointment(appointmentId: Int) {
        api.delete("/appointments/$appointmentId")
    }
}
  • 第 22 行:[api.get("/doctors").read()]:期望的类型 [List<Person>] 由函数的返回类型推断出来;
  • 第 28–31 行:[Uri.Builder] 构造参数字符串,并对必要的信息进行编码。

第三层:屏幕的状态和动作,位于 [ViewModel] 中(见示例 20)。这一次,状态由 [Compose] 属性([mutableStateOf])构成,当只有屏幕观察它们时,这比 [StateFlow] 更容易读:

// =========================================================================
// ex24/ScheduleModel.kt - 屏幕的“视图模型”
// -------------------------------------------------------------------------
// Android 架构指南建议将以下两者分开:
//   - 视图:@Composable 函数,负责显示并转发
//     用户的操作;
//   - 视图模型(ViewModel):屏幕的状态(所选医生、
//     日期、收到的日程等)、动作(选择、预约、取消),
//     以及对 API 访问层的调用。
// 视图不再有任何逻辑:它易于阅读;视图模型
// 没有组件:它易于测试。而且它能在
// Activity 被重新创建(屏幕旋转)后存活。
// 这些动作在 viewModelScope 中启动它们的协程:如果 ViewModel 被销毁
// (Activity 被彻底关闭),这些协程就会被取消。
//
// 它还完成我们不想为每个屏幕重写的工作:
//   - 缓存:已经读取过的每个(医生,日期)的日程都被保留;再次
//     回到它时会立即显示,同时在后台重新读取;
//   - 过期的响应会被忽略:新的读取会取消
//     上一次读取(参见示例 19)。
// =========================================================================
package fr.stahe.examples.ex24

import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.setValue
import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import fr.stahe.examples.common.Schedule
import fr.stahe.examples.common.ScheduleSlot
import fr.stahe.examples.common.ApiError
import fr.stahe.examples.common.Person
import fr.stahe.examples.common.Role
import fr.stahe.examples.common.User
import kotlinx.coroutines.Job
import kotlinx.coroutines.launch
import java.time.LocalDate

// 显示给用户的一条消息
data class Message(val success: Boolean, val text: String)

class ScheduleModel(private val rdvmedecins: RdvMedecins) : ViewModel() {
    // 状态:Compose 状态,只能在这里修改
    var user by mutableStateOf<User?>(null)
        private set
    var doctors by mutableStateOf(listOf<Person>())
        private set
    var clients by mutableStateOf(listOf<Person>())
        private set
    var doctorId by mutableStateOf<Int?>(null)
        private set
    var day by mutableStateOf(LocalDate.now().plusDays(1).toString()) // 明天,“2026-10-06”
        private set
    var clientId by mutableStateOf<Int?>(null)
        private set
    var schedule by mutableStateOf<Schedule?>(null)
        private set
    var loading by mutableStateOf(false)
        private set
    var message by mutableStateOf<Message?>(null)
        private set
    private val cache = mutableMapOf<String, Schedule>()
    private var reading: Job? = null

    // 计算值
    val loggedIn get() = user != null
    val isManager get() = user.let { it != null && it.role != Role.USER }

    // 动作
    fun changeUser(u: User?) {
        user = u
        doctors = emptyList()
        clients = emptyList()
        schedule = null
        doctorId = null
        cache.clear() // 权限已改变:一切都被遗忘
        if (u == null) return
        viewModelScope.launch {
            try {
                doctors = rdvmedecins.getDoctors()
                if (isManager) clients = rdvmedecins.getClients() // USER 会收到 403
            } catch (e: ApiError) {
                message = Message(false, e.toString())
            }
        }
    }

    fun chooseDoctor(id: Int?) {
        doctorId = id
        message = null
        readSchedule()
    }

    fun chooseDay(d: LocalDate) {
        day = d.toString()
        message = null
        readSchedule()
    }

    fun chooseClient(id: Int?) {
        clientId = id
    }

    fun book(s: ScheduleSlot) = act("Slot ${s.timeRange} booked.") {
        rdvmedecins.book(day, s.id, if (isManager) clientId else null)
    }

    fun cancel(s: ScheduleSlot) = act("Appointment at ${s.timeRange} cancelled.") { rdvmedecins.cancelAppointment(s.appointmentId!!) }

    // 一个动作,然后总是重新读取日程:服务器才是权威
    private fun act(success: String, action: suspend () -> Unit) {
        viewModelScope.launch {
            message = try {
                action()
                Message(true, success)
            } catch (e: ApiError) {
                Message(false, e.toString())
            }
            readSchedule()
        }
    }

    private fun readSchedule() {
        val id = doctorId ?: return
        val key = "$id/$day"
        // 一次较早的读取仍在进行:将其取消
        reading?.cancel()
        // 先是缓存(或什么都没有),然后是读取
        schedule = cache[key]
        loading = true
        reading = viewModelScope.launch {
            try {
                val read = rdvmedecins.getSchedule(id, day)
                cache[key] = read
                schedule = read
            } catch (e: ApiError) {
                schedule = null
                message = Message(false, e.toString())
            }
            loading = false
        }
    }
}
  • 第 44–62 行:状态,只能在这里修改;
  • 第 70–83 行:切换用户:一切都被清除(权限已改变),然后重新加载。[viewModelScope.launch]:一个与 [ViewModel] 同寿命的协程;
  • 第 111–119 行:每个动作总是以重新读取日程结束:服务器才是权威版本;
  • 第 123–140 行:读取日程:任何仍在进行的较早读取操作都会被取消;缓存提供立即的响应,随后被服务器的响应替换。

视图,只是显示模型。登录由一个可复用的组件处理,即 [common/LoginBar.kt] 栏(示例 23 的表单,使用 [Api] 重写):

// =========================================================================
// common/LoginBar.kt - 登录 / 退出登录,集中在一个栏中
// -------------------------------------------------------------------------
// 示例 23 的表单,精简为一个栏并用 Api.kt 重写。
// 每当已登录的用户(或 null)变化时,该组件都会用它调用 onUserChange,
// 包括启动时,在
// 查询 GET /api/auth/me 之后。供示例 24 和 25 使用。
// =========================================================================
package fr.stahe.examples.common

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.width
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.automirrored.filled.ExitToApp
import androidx.compose.material.icons.filled.Check
import androidx.compose.material.icons.filled.Person
import androidx.compose.material3.Card
import androidx.compose.material3.CardDefaults
import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.material3.OutlinedTextField
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.runtime.saveable.rememberSaveable
import androidx.compose.runtime.setValue
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.input.PasswordVisualTransformation
import androidx.compose.ui.unit.dp
import kotlinx.coroutines.launch
import kotlinx.serialization.json.buildJsonObject
import kotlinx.serialization.json.put

@Composable
fun LoginBar(api: Api, onUserChange: (User?) -> Unit) {
    var user by remember { mutableStateOf<User?>(null) }
    var captcha by remember { mutableStateOf<Captcha?>(null) }
    var login by rememberSaveable { mutableStateOf("admin") }
    var password by rememberSaveable { mutableStateOf("") }
    var captchaAnswer by rememberSaveable { mutableStateOf("") }
    var error by remember { mutableStateOf<String?>(null) }
    val scope = rememberCoroutineScope()

    fun changeUser(u: User?) {
        user = u
        onUserChange(u)
    }

    suspend fun newCaptcha() {
        captcha = api.get("/captcha").read<Captcha>()
        captchaAnswer = ""
    }

    // 启动时:我们是否已经登录?
    LaunchedEffect(Unit) {
        try {
            changeUser(api.get("/auth/me").read<User>())
        } catch (e: ApiError) {
            changeUser(null) // 401:没有人登录
            try {
                newCaptcha()
            } catch (e: ApiError) {
                error = "Is the JSON server running (${Config.serverUrl})?"
            }
        }
    }

    suspend fun logIn() {
        error = null
        try {
            val body = buildJsonObject {
                put("login", login.trim())
                put("password", password)
                put("captchaId", captcha?.id)
                put("captcha", captchaAnswer)
            }
            val u = api.post("/auth/login", body).read<User>()
            password = ""
            changeUser(u)
        } catch (e: ApiError) {
            error = e.toString() // “401 LOGIN.ERROR”
            runCatching { newCaptcha() }
        }
    }

    suspend fun logOut() {
        runCatching { api.post("/auth/logout") }
        changeUser(null)
        runCatching { newCaptcha() }
    }

    Card(colors = CardDefaults.cardColors(containerColor = Color(0xFFECEFF1))) {
        val u = user
        if (u != null) {
            Row(Modifier.padding(8.dp), verticalAlignment = Alignment.CenterVertically) {
                Icon(Icons.Default.Person, contentDescription = null)
                Spacer(Modifier.width(8.dp))
                Text("${u.name} (${u.role})", Modifier.weight(1f))
                TextButton(onClick = { scope.launch { logOut() } }) {
                    Icon(Icons.AutoMirrored.Filled.ExitToApp, contentDescription = null)
                    Text("Log out")
                }
            }
        } else {
            Column(Modifier.padding(8.dp)) {
                Row {
                    OutlinedTextField(login, { login = it }, label = { Text("login") }, singleLine = true, modifier = Modifier.weight(1f))
                    Spacer(Modifier.width(8.dp))
                    OutlinedTextField(
                        password,
                        { password = it },
                        label = { Text("password") },
                        singleLine = true,
                        visualTransformation = PasswordVisualTransformation(),
                        modifier = Modifier.weight(1f),
                    )
                }
                Row(verticalAlignment = Alignment.CenterVertically) {
                    // 验证码的 SVG 图像,由我们自己的服务器生成(参见示例 22)
                    captcha?.let { SvgImage(it.svg, height = 40.dp) }
                    Spacer(Modifier.width(8.dp))
                    OutlinedTextField(captchaAnswer, { captchaAnswer = it }, label = { Text("captcha") }, singleLine = true, modifier = Modifier.weight(1f))
                    IconButton(onClick = { scope.launch { logIn() } }) {
                        Icon(Icons.Default.Check, contentDescription = "Log in")
                    }
                }
                error?.let { Text(it, color = Color.Red) }
            }
        }
    }
}
// =========================================================================
// ex24/Ex24Activity.kt - 日程,使用 API 访问层
// -------------------------------------------------------------------------
// 登录(顶部栏),选择一位医生和一天:
// 随后显示日程。ADMIN 和 DOCTOR 可以为患者预约和
// 取消;患者(martin 等)为自己预约。每个动作
// 都以重新读取日程结束。
// 三个层次,自下而上:
//   Api (common/Api.kt)               HTTP 请求、错误;
//   RdvMedecins (RdvMedecins.kt)      API 的每个路由对应一个类型化的函数;
//   ScheduleModel (ScheduleModel.kt)  屏幕的状态和动作;
// 以及下面的视图,它只显示模型。
// =========================================================================
@file:OptIn(ExperimentalMaterial3Api::class)

package fr.stahe.examples.ex24

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.width
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.AddCircle
import androidx.compose.material.icons.filled.Close
import androidx.compose.material.icons.filled.DateRange
import androidx.compose.material3.Card
import androidx.compose.material3.CardDefaults
import androidx.compose.material3.DatePicker
import androidx.compose.material3.DatePickerDialog
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.material3.LinearProgressIndicator
import androidx.compose.material3.ListItem
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.SuggestionChip
import androidx.compose.material3.SuggestionChipDefaults
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.material3.rememberDatePickerState
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.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp
import androidx.lifecycle.viewmodel.compose.viewModel
import fr.stahe.examples.ExamplesApplication
import fr.stahe.examples.common.Api
import fr.stahe.examples.common.LoginBar
import fr.stahe.examples.common.ScheduleSlot
import fr.stahe.examples.common.DropdownList
import fr.stahe.examples.common.ExamplePage
import fr.stahe.examples.common.ExamplesTheme
import java.time.Instant
import java.time.LocalDate
import java.time.ZoneOffset

class Ex24Activity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        enableEdgeToEdge()
        val api = (application as ExamplesApplication).api
        setContent { ExamplesTheme { SchedulePage(api) } }
    }
}

@Composable
fun SchedulePage(api: Api) {
    // viewModel { ... }:Activity 的模型,在第一次请求时由这个代码块创建
    // (它需要一个参数:API 访问层)
    val model = viewModel { ScheduleModel(RdvMedecins(api)) }
    var calendarOpen by remember { mutableStateOf(false) }

    ExamplePage("Example 24 - an API access layer") {
        LoginBar(api, onUserChange = { model.changeUser(it) })
        if (model.loggedIn) {
            DropdownList(
                label = "Doctor",
                value = model.doctorId,
                choices = listOf<Int?>(null) + model.doctors.map { it.id },
                text = { id -> model.doctors.find { it.id == id }?.fullName ?: "-- choose a doctor --" },
                onChange = { model.chooseDoctor(it) },
                modifier = Modifier.fillMaxWidth(),
            )
            Row(verticalAlignment = Alignment.CenterVertically) {
                Text("Day: ${model.day}")
                IconButton(onClick = { calendarOpen = true }) { Icon(Icons.Default.DateRange, contentDescription = "choose the day") }
            }
            if (model.isManager) {
                DropdownList(
                    label = "Patient",
                    value = model.clientId,
                    choices = listOf<Int?>(null) + model.clients.map { it.id },
                    text = { id -> model.clients.find { it.id == id }?.fullName ?: "-- patient to book for --" },
                    onChange = { model.chooseClient(it) },
                    modifier = Modifier.fillMaxWidth(),
                )
            }
            model.message?.let { m ->
                Card(colors = CardDefaults.cardColors(containerColor = if (m.success) Color(0xFFE8F5E9) else Color(0xFFFFEBEE))) {
                    Text(m.text, Modifier.padding(10.dp))
                }
            }
            if (model.loading) LinearProgressIndicator(Modifier.fillMaxWidth())
            model.schedule?.let { schedule ->
                // info:当患者已经有一个未来的预约时,服务器发送的键
                schedule.info?.let { Text(it, color = Color(0xFF1976D2)) }
                Text(
                    "Schedule of ${schedule.day} - ${schedule.doctor.fullName}",
                    style = MaterialTheme.typography.titleSmall,
                    modifier = Modifier.padding(vertical = 8.dp),
                )
                for (s in schedule.slots) {
                    SlotRow(s, onBook = { model.book(s) }, onCancel = { model.cancel(s) })
                }
            }
        }
    }

    if (calendarOpen) {
        val state = rememberDatePickerState(
            initialSelectedDateMillis = LocalDate.parse(model.day).atStartOfDay(ZoneOffset.UTC).toInstant().toEpochMilli(),
        )
        DatePickerDialog(
            onDismissRequest = { calendarOpen = false },
            confirmButton = {
                TextButton(onClick = {
                    state.selectedDateMillis?.let { model.chooseDay(Instant.ofEpochMilli(it).atZone(ZoneOffset.UTC).toLocalDate()) }
                    calendarOpen = false
                }) { Text("OK") }
            },
        ) { DatePicker(state = state) }
    }
}

// 日程的一行:时间范围、占用者、允许的按钮
@Composable
fun SlotRow(s: ScheduleSlot, onBook: () -> Unit, onCancel: () -> Unit) {
    ListItem(
        leadingContent = { Text(s.timeRange, Modifier.width(96.dp)) },
        headlineContent = {
            if (s.free) {
                SuggestionChip(
                    onClick = {},
                    label = { Text("Free") },
                    colors = SuggestionChipDefaults.suggestionChipColors(containerColor = Color(0xFFC8E6C9)),
                )
            } else {
                SuggestionChip(
                    onClick = {},
                    label = { Text(s.patient?.toString() ?: "Booked") },
                    colors = SuggestionChipDefaults.suggestionChipColors(
                        containerColor = if (s.mine) Color(0xFFC5CAE9) else Color(0xFFE0E0E0),
                    ),
                )
            }
        },
        // 按钮跟随服务器计算出的权限
        trailingContent = {
            when {
                s.bookable -> IconButton(onClick = onBook) {
                    Icon(Icons.Default.AddCircle, contentDescription = "Book", tint = Color(0xFF2E7D32))
                }
                s.appointmentId != null -> IconButton(onClick = onCancel) {
                    Icon(Icons.Default.Close, contentDescription = "Cancel", tint = Color.Red)
                }
            }
        },
    )
}
  • 第 79 行:[viewModel [ ... ]]:模型,在首次请求时由这个代码块创建(它需要一个参数);
  • 第 86–90 行:医生列表:它的选项是 [Int?],而“-- choose a doctor --”对应 [null];
  • 第 169–172 行:每一行上的按钮对应于服务器计算出的权限([bookable]、[appointmentId])。

Image

Image

Image

左图和中图:ADMIN 为 Jean MARTIN 预订第一个时间段;右图:以 [martin] 身份登录:服务器把所有时间段的 [bookable] 都设为 [false],因为这位患者已经有一个未来的预约,键 [SCHEDULE.ALREADY_BOOKED_INFO] 对此作了说明。这个原始的键没有多大意义:示例 25 会翻译服务器的键。

9.4. 示例 25:服务器返回的错误

服务器会验证它收到的一切(见示例 07),并在拒绝时返回一个 JSON 错误,其中给出总体消息的键和每个字段的错误键:

1
2
3
400 { key: 'ERRORS.INVALID_FORM', fields: { lastName: 'ERRORS.LASTNAME_REQUIRED' } }
409 { key: 'ERRORS.PATIENT_ALREADY_EXISTS', fields: { firstName: ..., lastName: ... } }
409 { key: 'ERRORS.CONCURRENT_UPDATE' }

这样的键有很多。服务器的客户端,即 [Vue.js]、[Angular]、[React] 和 [Flutter],使用 JSON 字典来翻译它们,每种语言一个字典。与其把这几百条文本复制到 [strings.xml] 文件中(并编写示例 21 中那种键到资源的对照表),我们不如原样复用这些字典,把它们存放在应用的 [assets/] 文件夹中:这些文件随应用一起打包,通过路径读取([assets/i18n/ex25_fr.json]、[ex25_en.json]):

// =========================================================================
// ex25/Dictionary.kt - 与其他客户端共享的字典
// -------------------------------------------------------------------------
// RdvMedecins 服务器只返回键(“ERRORS.LOGIN_TAKEN”),
// 而且数量很大:每个字段、每个
// 路由的错误消息……该服务器的 Web 客户端(Vue.js、Angular、React)和 Flutter 客户端
// 使用 JSON 字典来翻译它们,每种语言一个字典,其中
// 每段文本都有它的键:
//     { "ERRORS": { "LOGIN_TAKEN": "This login is already used..." } }
// 与其把这几百条文本复制到 strings.xml 文件中(并
// 编写示例 21 中那种键 -> 资源的对照表),我们不如原样复用这些
// 字典。它们存放在应用的 assets/ 文件夹中:
// 随应用一起打包的文件,通过路径读取。
//   - t("FORM.ADDED", mapOf("name" to "Marie DUPONT")):当前语言的
//     文本,其中的 {{name}} 参数会被替换;
//   - 未知的键会原样显示:我们可以看到缺少了什么。
// 语言仍然是应用的语言(示例 21):字典
// 据此选择。
// =========================================================================
package fr.stahe.examples.ex25

import android.content.Context
import androidx.compose.runtime.Composable
import androidx.compose.runtime.remember
import androidx.compose.ui.platform.LocalConfiguration
import androidx.compose.ui.platform.LocalContext
import kotlinx.serialization.json.Json
import kotlinx.serialization.json.JsonElement
import kotlinx.serialization.json.JsonObject
import kotlinx.serialization.json.JsonPrimitive

class Dictionary(context: Context, file: String) {
    // JSON 文件的内容,一次性读取
    private val root: JsonObject = context.assets.open(file).bufferedReader().use { reader ->
        Json.parseToJsonElement(reader.readText()) as JsonObject
    }

    // "FORM.ADDED" -> root["FORM"]["ADDED"];缺失时为 null
    private fun find(key: String): String? {
        var node: JsonElement? = root
        for (part in key.split('.')) {
            node = (node as? JsonObject)?.get(part)
        }
        return (node as? JsonPrimitive)?.takeIf { it.isString }?.content
    }

    fun t(key: String, params: Map<String, String> = emptyMap()): String {
        val text = find(key) ?: return key
        // {{name}} -> name 参数的值(如果没有提供,则保持 {{name}})
        return Regex("\\{\\{(\\w+)\\}\\}").replace(text) { m -> params[m.groupValues[1]] ?: m.value }
    }
}

// 当前语言的字典:assets/i18n/<prefix>_<language>.json
@Composable
fun rememberDictionary(prefix: String): Dictionary {
    val context = LocalContext.current
    val language = LocalConfiguration.current.locales[0].language.let { if (it == "fr") "fr" else "en" }
    // 只有当语言改变时才重新读取
    return remember(language) { Dictionary(context, "i18n/${prefix}_$language.json") }
}
  • 第 34–35 行:JSON 文件,一次性读取([context.assets.open]);
  • 第 39–48 行:["FORM.ADDED"] → [root["FORM"]["ADDED"]];未知的键会原样显示:我们可以看到缺少了什么;
  • 第 50 行:[{{name}}] 参数通过正则表达式替换;
  • 第 56–60 行:应用语言(示例 21)的字典,只有在语言改变时才重新读取。

屏幕的模型:这个表单在手机上不做任何验证;所有内容都发送给服务器。

// =========================================================================
// ex25/ClientsModel.kt - 客户屏幕的状态
// -------------------------------------------------------------------------
// 这个表单有意不在手机上做任何验证:
// 所有内容都发送给服务器,服务器在拒绝时会返回一个 JSON
// 错误(由 common/Api.kt 转换为 ApiError):
//
//   400 { key: 'ERRORS.INVALID_FORM', fields: { lastName: 'ERRORS.LASTNAME_REQUIRED' } }
//   409 { key: 'ERRORS.PATIENT_ALREADY_EXISTS', fields: { firstName: ..., lastName: ... } }
//   409 { key: 'ERRORS.CONCURRENT_UPDATE' }         (乐观锁)
//
// 每个字段的错误(ApiError.fields)存放在状态中,并
// 显示在该字段下方;它的消息是服务器发送的键,
// 由屏幕来翻译。修改字段会清除它的错误。
// 状态位于 ViewModel 中:更改语言会重新创建 Activity
// (参见示例 21),而正在进行的输入不能丢失。
// =========================================================================
package fr.stahe.examples.ex25

import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.setValue
import androidx.lifecycle.ViewModel
import fr.stahe.examples.common.Api
import fr.stahe.examples.common.ApiError
import fr.stahe.examples.common.Person
import fr.stahe.examples.common.Role
import fr.stahe.examples.common.User
import fr.stahe.examples.common.read
import fr.stahe.examples.ex23.Command
import kotlinx.serialization.json.buildJsonObject
import kotlinx.serialization.json.put

// 一条待翻译的消息:一个键及其参数
data class KeyMessage(val key: String, val params: Map<String, String> = emptyMap())

class ClientsModel(private val api: Api) : ViewModel() {
    var user by mutableStateOf<User?>(null)
        private set
    var clients by mutableStateOf(listOf<Person>())
        private set

    // 表单:editedId == null -> 创建,否则为更新
    var editedId by mutableStateOf<Int?>(null)
        private set
    private var version = 0

    // 输入的值,按字段名存放(服务器期望的名称)
    var input by mutableStateOf(empty)
        private set

    // 每个字段的错误(一个翻译键),由服务器返回
    var errors by mutableStateOf(mapOf<String, String>())
        private set

    // 最近一次错误的总体消息,以及成功时的消息
    var pageError by mutableStateOf<ApiError?>(null)
        private set
    var success by mutableStateOf<KeyMessage?>(null)
        private set

    // 发送给服务器:一个 Command(示例 23),它说明是否正在进行
    val sending = Command()

    val isAdmin get() = user?.role == Role.ADMIN

    suspend fun onUserChange(u: User?) {
        user = u
        clients = emptyList()
        if (u?.role == Role.ADMIN) reload()
    }

    private suspend fun reload() {
        clients = try {
            api.get("/clients").read()
        } catch (e: ApiError) {
            emptyList()
        }
    }

    private fun clearMessages() {
        errors = emptyMap()
        pageError = null
        success = null
    }

    // 被修改的字段:它的值改变,它的错误消失
    fun change(field: String, value: String) {
        input = input + (field to value)
        errors = errors - field
    }

    fun newForm() {
        editedId = null
        version = 0
        input = empty
        clearMessages()
    }

    fun edit(c: Person) {
        editedId = c.id
        // 随记录一起读取的版本(VERSION)会随更新一起发回:如果
        // 在此期间有人修改了该记录,服务器会返回 409
        // CONCURRENT_UPDATE
        version = c.version
        input = mapOf("title" to c.title, "firstName" to c.firstName, "lastName" to c.lastName, "login" to (c.login ?: ""), "password" to "")
        clearMessages()
    }

    suspend fun save() {
        clearMessages()
        val body = buildJsonObject {
            for ((field, value) in input) put(field, value)
            put("version", version)
        }
        try {
            val id = editedId
            val client: Person = (if (id == null) api.post("/clients", body) else api.put("/clients/$id", body)).read()
            val key = if (id == null) "FORM.ADDED" else "FORM.UPDATED"
            newForm() // 表单被清空,消息被清除……
            // ……除了这一条
            success = KeyMessage(key, mapOf("name" to "${client.firstName} ${client.lastName}", "login" to (client.login ?: "")))
            reload()
        } catch (e: ApiError) {
            pageError = e // 总体消息
            errors = e.fields // 每个字段的错误
        }
    }

    suspend fun remove(c: Person) {
        clearMessages()
        try {
            api.delete("/clients/${c.id}")
            success = KeyMessage("FORM.DELETED", mapOf("name" to "${c.firstName} ${c.lastName}"))
        } catch (e: ApiError) {
            pageError = e
        }
        reload()
    }

    companion object {
        val empty = mapOf("title" to "Mr", "firstName" to "", "lastName" to "", "login" to "", "password" to "")
    }
}
  • 第 49–53 行:按字段名(服务器期望的名称)存放的输入,以及每个字段的错误(一条翻译);
  • 第 88–90 行:修改字段会清除它的错误;
  • 第 105 行:从记录中读取的版本(VERSION)会随修改一起发回;如果在此期间有人修改了该记录,服务器会返回 409 [CONCURRENT_UPDATE](乐观锁);
  • 第 110–126 行:保存:出错时,总体消息和每个字段的错误([e.fields])会存入状态。

屏幕:

// =========================================================================
// ex25/Ex25Activity.kt - 显示服务器返回的错误
// -------------------------------------------------------------------------
// 客户管理(管理员账户),参见 ClientsModel.kt。屏幕在每个字段下方
// 显示服务器附加给它的错误,
// 由字典(Dictionary.kt)翻译,并在表单底部
// 显示总体消息。
// 试试:空姓名、“Dr”称谓、同名者(Alice DURAND)、
// 已被占用的登录名(martin)、在两台设备上修改的同一条记录……
// =========================================================================
package fr.stahe.examples.ex25

import android.os.Bundle
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.appcompat.app.AppCompatActivity
import androidx.appcompat.app.AppCompatDelegate
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.width
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Edit
import androidx.compose.material.icons.filled.MoreVert
import androidx.compose.material.icons.outlined.Delete
import androidx.compose.material3.Button
import androidx.compose.material3.Card
import androidx.compose.material3.CardDefaults
import androidx.compose.material3.DropdownMenu
import androidx.compose.material3.DropdownMenuItem
import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.material3.ListItem
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.OutlinedButton
import androidx.compose.material3.OutlinedTextField
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.rememberCoroutineScope
import androidx.compose.runtime.setValue
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.SpanStyle
import androidx.compose.ui.text.buildAnnotatedString
import androidx.compose.ui.text.input.PasswordVisualTransformation
import androidx.compose.ui.text.input.VisualTransformation
import androidx.compose.ui.text.withStyle
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp
import androidx.core.os.LocaleListCompat
import androidx.lifecycle.viewmodel.compose.viewModel
import fr.stahe.examples.ExamplesApplication
import fr.stahe.examples.common.Api
import fr.stahe.examples.common.LoginBar
import fr.stahe.examples.common.DropdownList
import fr.stahe.examples.common.ExamplePage
import fr.stahe.examples.common.ExamplesTheme
import fr.stahe.examples.ex16.ConfirmDialog
import fr.stahe.examples.ex16.rememberConfirmation
import kotlinx.coroutines.launch

class Ex25Activity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        enableEdgeToEdge()
        val api = (application as ExamplesApplication).api
        setContent { ExamplesTheme { ClientsPage(api) } }
    }
}

@Composable
fun ClientsPage(api: Api) {
    val model = viewModel { ClientsModel(api) }
    val dict = rememberDictionary("ex25")
    // 一个快捷方式:t("KEY") 调用 dict.t("KEY")
    fun t(key: String, params: Map<String, String> = emptyMap()) = dict.t(key, params)
    val confirmation = rememberConfirmation()
    val scope = rememberCoroutineScope()
    var languageMenu by remember { mutableStateOf(false) }

    // 一个输入字段,带有翻译后的错误(一个服务器键)
    @Composable
    fun Field(field: String, secret: Boolean = false) {
        val error = model.errors[field]
        OutlinedTextField(
            value = model.input[field].orEmpty(),
            onValueChange = { model.change(field, it) },
            label = { Text(t("FORM.${field.uppercase()}")) },
            singleLine = true,
            isError = error != null,
            supportingText = error?.let { e -> { Text(t(e)) } },
            visualTransformation = if (secret) PasswordVisualTransformation() else VisualTransformation.None,
            modifier = Modifier.fillMaxWidth(),
        )
    }

    ExamplePage(
        title = t("FORM.PAGE_TITLE"),
        // 语言:一个菜单
        actions = {
            IconButton(onClick = { languageMenu = true }) { Icon(Icons.Default.MoreVert, contentDescription = "language") }
            DropdownMenu(expanded = languageMenu, onDismissRequest = { languageMenu = false }) {
                for (l in listOf("fr", "en")) {
                    DropdownMenuItem(text = { Text(l.uppercase()) }, onClick = {
                        languageMenu = false
                        AppCompatDelegate.setApplicationLocales(LocaleListCompat.forLanguageTags(l))
                    })
                }
            }
        },
    ) {
        LoginBar(api, onUserChange = { u -> scope.launch { model.onUserChange(u) } })
        if (model.user != null && !model.isAdmin) {
            Card(colors = CardDefaults.cardColors(containerColor = Color(0xFFFFF8E1))) {
                Text(t("FORM.ADMIN_ONLY"), Modifier.padding(12.dp))
            }
        }
        if (model.isAdmin) {
            for (c in model.clients) {
                ListItem(
                    headlineContent = { Text(c.fullName) },
                    supportingContent = { Text(c.login ?: "") },
                    trailingContent = {
                        Row {
                            IconButton(onClick = { model.edit(c) }) { Icon(Icons.Default.Edit, contentDescription = t("FORM.EDIT")) }
                            IconButton(onClick = {
                                scope.launch {
                                    val name = "${c.firstName} ${c.lastName}"
                                    if (confirmation.confirm(t("FORM.DELETE_CONFIRM", mapOf("name" to name)))) model.remove(c)
                                }
                            }) {
                                Icon(Icons.Outlined.Delete, contentDescription = t("FORM.DELETE"), tint = Color.Red)
                            }
                        }
                    },
                )
            }
            Card(Modifier.fillMaxWidth()) {
                Column(Modifier.padding(12.dp)) {
                    Text(t(if (model.editedId == null) "FORM.TITLE_ADD" else "FORM.TITLE_EDIT"), style = MaterialTheme.typography.titleMedium)
                    // 服务器会拒绝的“Dr”称谓:用来看到 ERRORS.INVALID_TITLE
                    DropdownList(
                        label = t("FORM.TITLE"),
                        value = model.input["title"].orEmpty(),
                        choices = listOf("Mr", "Mme", "Melle", "Dr"),
                        onChange = { model.change("title", it) },
                        error = model.errors["title"]?.let { t(it) },
                        modifier = Modifier.width(200.dp),
                    )
                    Field("firstName")
                    Field("lastName")
                    Field("login")
                    Field("password", secret = true)
                    Row(Modifier.padding(top = 12.dp)) {
                        Button(onClick = { scope.launch { model.sending.execute { model.save() } } }, enabled = !model.sending.inProgress) {
                            Text(t("FORM.SAVE"))
                        }
                        Spacer(Modifier.width(8.dp))
                        OutlinedButton(onClick = { model.newForm() }) { Text(t("FORM.CANCEL")) }
                    }
                    model.success?.let { s ->
                        Text(t(s.key, s.params), color = Color(0xFF2E7D32), modifier = Modifier.padding(top = 12.dp))
                    }
                    // 总体消息和 HTTP 状态,便于理解
                    model.pageError?.let { e ->
                        Text(
                            buildAnnotatedString {
                                withStyle(SpanStyle(color = Color.Red)) { append(t(e.key, e.params)) }
                                withStyle(SpanStyle(color = Color.Gray, fontSize = 12.sp)) { append("  ($e)") }
                            },
                            modifier = Modifier.padding(top = 12.dp),
                        )
                    }
                }
            }
        }
    }
    ConfirmDialog(confirmation)
}
  • 第 79–81 行:字典,以及一个快捷函数 [t(...)];
  • 第 88–96 行:一个字段及其错误,一个经过翻译的服务器键;
  • 第 106–111 行:语言,位于顶部栏的菜单中([DropdownMenu]);
  • 第 170–174 行:总体消息和 HTTP 状态,仅供参考。

Image

Image

Image

左图:名和姓为空的记录:错误 400;中图:与 Alice DURAND 同名者:错误 409;右图:同一个错误的法语版:当前的输入在 Activity 被重新创建后依然保留,这要归功于 [ViewModel]。