p1xt-guides Android 实战指南：用 theMovieDB API 构建 Popular Movies 电影发现应用（Stage 1）

• 教程
• 文档

本文是 p1xt-guides 仓库中 Udacity Android Nanodegree 项目作业 Popular Movies, Stage 1 的完整技术指南。该作业对应 Android 学习路径中的第一个"联网型"实战项目：你将构建一个电影发现 App，通过 theMovieDB API 拉取热门电影数据，以海报网格形式呈现，并支持按人气与评分切换排序、点击查看详情。读完本文，你将掌握多 Activity 界面搭建、Intent 跳转、网络数据获取、Adapter 与自定义列表布局的完整实战套路，并了解该阶段项目在 Android 综合指南 Tier 2 中的定位与验收标准。

项目概述：第一阶段要交付什么

Popular Movies 是面向 Android 开发者核心基本功的经典实战项目，被拆分为两个阶段递进完成。Stage 1 构建的是"核心体验"——一个能联网发现热门电影的最小可用产品。

启动 App 后，用户应能看到：

• 海报网格：应用启动即呈现一个电影海报的网格排列（grid arrangement of movie posters），这是整个 Stage 1 的主界面。
• 可切换的排序方式：用户可通过设置（setting）改变排序规则，可选"按人气最高（most popular）"或"按评分最高（highest-rated）"。
• 点击进入详情页：用户点击任意一张海报，页面过渡（transition）到详情屏幕，展示该电影的补充信息，包括：
  • 原始标题（original title）；
  • 电影海报缩略图（movie poster image thumbnail）；
  • 剧情概要——API 中字段名为overview；
  • 用户评分——API 中字段名为vote_average；
  • 上映日期（release date）。

这些字段名直接来自 theMovieDB API 的响应结构，在后续解析 JSON 时需要原样对应。

为什么做这个项目：能力目标拆解

要成为合格的 Android 开发者，必须能把特定的移动端体验落地成真。本项目刻意聚焦于三项 Android 开发的基本功，它们共同构成了 Stage 1 的验收核心：

1. 构建干净、有吸引力的用户界面（UI）——海报网格 + 详情页，考验布局组织能力；
2. 从网络服务获取数据（network services）——与 theMovieDB API 通信，考验网络层处理；
3. 针对多种移动设备优化体验——网格与详情布局要适配不同屏幕尺寸。

原文档明确指出：通过完成 Stage 1，你要证明自己对 Android 编程基础要素的理解，让 App 能与互联网通信，并提供"响应迅速、体验愉悦"的用户交互。

学习目标：Stage 1 结束后你将掌握什么

原文档列出了三项明确的学习产出，它们也是自查清单：

• 使用 theMovieDB API 从互联网获取数据：包括构造请求 URL、解析 JSON 响应、处理异步网络回调；
• 使用 Adapter 与自定义列表布局填充列表视图：海报网格背后的每个单元格如何由数据驱动生成，是这一阶段的核心编码量；
• 引入第三方库来精简代码量：原文档特意强调"incorporate libraries to simplify the amount of code you need to write"——这是引导你养成"不重复造轮子、合理引入成熟库"工程习惯的节点。

说明：该作业诞生于 2015–2017 年间的 Udacity Nanodegree 课程背景，当时的典型技术组合（如GridView/RecyclerView+AsyncTask+Gson+Picasso）可作为参考，但具体选型以你当前学习的 Android 课程版本为准。

前置条件与配套课程

原文档明确建议：完成 Developing Android Apps 课程的第 1–3 课之后，你就具备了完成本 App 所需的核心技能。若想进一步打磨界面美观度，可再学习该课程第 5 课中关于"如何制作更精细布局（more detailed layouts）"的材料。

在 p1xt-guides 的整体学习路径中，该项目被编排在 Native Android Programming 综合指南 的Tier 2（Intermediate Android），紧随 Developing Android Apps、Build it Bigger、Make Your App Material 等中级项目同层。此前 Tier 1 的 Android Basics: Networking、News App 等联网项目已经为你铺垫了网络请求与列表展示的基础，因此进入 Stage 1 时不应从零开始。该作业同时出现在 Android Speedrun/Practice 清单 中，也可作为高强度实操练习使用。

必需任务：三项硬性交付

原文档将 Stage 1 的实现收敛为三个必须完成的任务：

1. 为多个 Activity 构建 UI 布局——至少包含主界面（海报网格）与详情界面两个 Activity 的布局文件；
2. 通过 Intent 启动这些 Activity——点击海报项时，用显式 Intent 携带电影数据跳转到详情 Activity；
3. 从 theMovieDB API 获取数据——实现网络请求与结果解析。

任务拆解与实现要点

任务一：海报网格主界面。主 Activity 的布局核心是一个可滚动的网格容器。Android 中通常使用GridView或RecyclerView（配合GridLayoutManager）承载海报。每个网格项（item）是一个自定义布局，典型结构为一张ImageView展示海报缩略图；网格项布局正是"自定义列表布局（custom list layouts）"所指的内容。

任务二：Adapter 数据桥接。网格与数据之间的桥梁是 Adapter：继承BaseAdapter或RecyclerView.Adapter，在getView/onBindViewHolder中把单个电影对象（标题、海报路径、评分等字段）绑定到 item 布局的各个视图上。原文档所说的"使用适配器和自定义列表布局来填充列表视图"，指的就是这层数据驱动渲染逻辑。

任务三：Intent 跳转与数据传递。用户点击海报后，主界面通过startActivity(intent)进入详情 Activity，电影数据既可以通过Intent的 extra 直接传递（适合字段较少的场景），也可以传递电影在数据源中的标识、由详情页按需再查询（适合字段丰富的场景）。两种思路在真实项目中都很常见，可按字段量权衡。

任务四：theMovieDB API 数据流。网络层需要完成四个环节：拼接带 API Key 的请求 URL → 发起 HTTP 请求（异步，避免阻塞主线程）→ 解析 JSON（映射到电影的overview、vote_average、release_date等字段）→ 把结果交给 Adapter 刷新网格。排序切换则体现为请求参数的变化：按人气排序与按评分排序对应 theMovieDB 的/popular与/top_rated端点（或等价查询参数）。第三方库（如 HTTP 客户端、JSON 解析库、图片加载库）正是"简化代码量"这一学习目标的具体落点。

API Key 的安全管理

theMovieDB 要求请求携带开发者自己的 API Key。原文档在提交规范中给出了一条重要红线：公开仓库中严禁出现 API Key（这既不安全，也常违反服务条款）。工程上推荐的实践是：把 Key 放入gradle.properties或local.properties（均已被.gitignore排除），再通过buildConfigField注入BuildConfig，使源码中只出现BuildConfig.API_KEY的引用而看不到明文；若通过公开仓库提交，应在 README 中注明评审者应在何处填入自己的 Key——原文档明确说明"评审者已接受过应对这种情况的培训"。

评分标准（Rubric）与提交规范

原文档强调，项目将由 Udacity 代码评审员按专属 Rubric 评估，所有标准必须达到 "meet specifications" 才算通过，提交前务必逐条核对。除此之外还需注意：

• 清理项目再提交：创建 zip 或推送 GitHub 前，务必执行项目清理（clean your project），避免把构建缓存、临时文件带进提交物；
• 分支要求：若用 GitHub 托管，用于评审的代码必须位于仓库的master分支；
• API Key 移除：如前述，公共仓库中的 Key 必须清除，并在 README 中指引评审者插入自己的 Key；
• 评审周期：提交量较大时，评审反馈最长可能需要一周，需预留时间；
• 通用要求叠加：除本项目专属 Rubric 外，所有 Android Nanodegree 项目还需满足 Common Project Requirements 的通用规范。

从 Stage 1 到 Stage 2：本阶段在整体项目中的位置

Stage 1 有意保持范围收敛——只做"发现电影"的核心闭环，不涉及本地存储与多媒体播放。它的后继项目 Popular Movies, Stage 2 会在同一 App 上追加：预告片播放（YouTube App 或浏览器）、影评阅读、详情页星标收藏（本地收藏集，无需 API 请求）、主界面增加"我的收藏"排序维度，以及面向平板（tablet）的双栏优化。因此，Stage 1 中确立的数据模型、Adapter 结构、网络层与详情页骨架，将直接作为 Stage 2 的扩展基础——这也解释了为什么 Stage 1 要求你把多 Activity 结构、Intent 传参和 API 解析写得足够干净。

常见问题与自查清单

• 排序切换不生效？检查排序参数是否真正改变了请求端点/查询参数，以及新数据返回后是否触发了 Adapter 的数据刷新与网格重绘。
• 详情页字段对不上？逐一核对 API 响应字段名：overview（剧情概要）、vote_average（评分）、release_date（上映日期），JSON 键名大小写与层级必须与响应结构一致。
• 网络在主线程崩溃？确认请求在后台线程执行（AsyncTask、Loader 或线程池方案），严禁在主线程做网络 I/O。
• 海报不显示？检查海报图片 URL 的拼接（通常为基础图片地址 + 尺寸路径 + 海报相对路径），并确认图片加载库已正确配置。
• 提交前最后检查：项目是否 clean？代码是否在 master 分支？公开仓库是否已移除 API Key？Rubric 每一条是否都达到了 "meet specifications"？

按上述清单逐项自检通过后，Stage 1 即告完成。你可以接着进入 Popular Movies, Stage 2，或按 Native Android Programming 综合指南 继续 Tier 2 的后续项目。

• 教程
• 文档