此笔记位置已失效,请从目录继续阅读。
全书导读
本书是Dan Sanderson编写的Programming Google App Engine中文译本,由唐学韬、何继业翻译,机械工业出版社2010年出版。它围绕早期GAE运行时、数据存储、缓存、外部服务、异步工作和部署管理,分别展示Python与Java接口。本轮完整读取本册范围;历史示例的运行时、接口、免费额度、限额和控制台均不能作为当前平台的兼容或供给承诺。
全书主线
托管平台把应用的执行、持久数据和可扩展服务分开,应用则要按这些边界组织请求与状态。先理解运行时约束,再认识实体与索引,把一致性要求落实到事务范围,随后用建模接口、缓存和异步任务连接业务。外部通信、批量工具和部署管理处理持续运行中不同的责任,不能只用一个API调用是否成功代替整体正确性。
前置说明
GAE是把应用托管到平台运行的一种开发方式:平台提供执行、数据和资源服务,开发者按其边界组织业务。前言用早期容量投入与突发增长的矛盾解释这种方式的吸引力,同时强调数据访问模型需要先行设计。本书按Python与Java两条接口线展开,先认识底层存储,再理解高级建模接口。这里的语言支持判断和服务承诺都处于2010年语境,后续各章会给出实际约束。
译者序
译者将托管平台描述为逻辑、数据和资源的基础服务,说明15章及Python/Java双线;译者对当时Python支持的偏好是2010年语境,不当作当前语言选型结论。
托管平台为应用逻辑、持久数据和静态资源提供运行基础,使开发者把主要精力放在业务。平台接手部分基础设施职责,也会规定应用可采用的运行与访问方式;不能把“其他一切交给平台”理解成无需数据设计、访问控制或运行管理。这里是本书2010年的GAE模型。
平台可分为运行时环境、数据存储区和可伸缩服务:它们分别处理执行、持久状态与专门能力。应用使用这些边界,而不是自行决定每次请求落在哪台物理服务器。
图像处理服务是专门能力的一个例子:应用提交图片转换需求,由独立服务完成缩略图等轻量转换。本书不展开其API,因此不补造接口、格式或算法步骤。
请求可分发给彼此不知情的处理器,业务状态仍须由共享数据服务维护。平台隐藏集群运维,不替应用决定并发更新、查询形状与一致性范围。
托管平台分开应用与设施补充本节结论的独立卡片及原书依据。
前言
前言从突发流量、前期容量投入与产品反馈的矛盾引出按使用供给资源。GAE不仅出租服务器,还规定分布式数据与服务模型;采用该模型需要提前设计数据访问,营销式的无需再架构不作无条件保证。
先建超大系统可能浪费早期投入,等增长后再扩又可能错失用户反馈。托管平台可承担部分供给、负载分配和故障处理,但可扩展应用仍须按平台的数据访问与分布模型设计;传统单机数据库依赖不能自动随服务器增加而消失。弹性资源与应用能否正确扩展是不同责任。
弹性供给仍需先设计数据补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
使用本书
本书按共同知识点分章,在需要处分别讲Python与Java。数据存储先介绍低级实体概念和API,再讲Python建模与Java JPA映射;章节导览不能替代后续正文。
低级数据存储API直接面对实体、键和属性;高层建模或持久化API在这些能力之上提供应用对象的表示和操作。先认识存储概念,有助于判断高层接口到底映射了什么;不能仅从接口名称推断它拥有关系数据库的全部能力。具体映射和限制还须结合后续各语言章节。
高层模型仍受底层存储约束补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
致谢
致谢说明GAE团队、数据存储和语言API贡献者,不将历史身份当成当前任职。附带Test Fixture释义说明测试所需材料,以最小术语卡保留,不把其位置误归到实质部署步骤。
测试夹具(Test Fixture)指测试运行所需要的准备材料,书中特别强调数据。理解测试时要分清准备了哪些输入和状态,以及测试本身检查了什么;准备夹具不等于已经验证行为。此处只是术语定义,不据此补造本书未在该处展开的测试流程。
这里的fixture具体体现为测试前加载的实体数据,setUp补充每次预备条件,tearDown清理;测试执行器的模拟隔离不等于真实线上服务行为一致。
本节明确每个测试重新清空模拟库并装载fixture,再运行setUp、测试与tearDown;手工loaddata与测试执行器自动装载的作用域要区别。
测试夹具准备测试所需材料补充本节结论的独立卡片及原书依据。
第1章 GAE简介
GAE把运行时、持久存储和专门服务分开:请求被路由到实例执行,静态资源可直接分流,实例内存仅适合可重建状态。持久数据以实体、键和属性表达,查询依赖预先维护的索引;实体组事务再给共同更新划定边界,冲突重试需要重新读取和计算。缓存与外部通信各有生命周期,队列则把工作交给后续处理器,不能把异步理解成无限运行。SDK帮助本地模拟与远程维护,控制台管理身份、版本和资源;这些入口的权限、状态及成本都要分开观察。最后的能力缺口清单仅说明2010年的条件,不能当作当前GAE功能表。
第1章 GAE简介
GAE简介将平台分为运行时、数据存储和可扩展服务。弹性资源、按用量计费与配额不是同一保证;原书GB泛化和免费PV估算不作为计量或容量承诺。
按使用量付费说明资源消耗与成本的关系,并不保证某个访问量必定免费或必定得到相同延迟。CPU、存储容量、出入口带宽是不同计量维度,不能照原文“均换算成GB”推断其单位。书中的免费额度与500万PV估算只属于当时说明,实际应用仍需核对各资源消耗和限制。
控制台一节分别列出CPU时间、带宽、存储和邮件收件人数量,进一步说明资源计量维度不同;第1章开头“均换算成GB”的泛化不能据此解释计费。
资源计费不等于容量承诺补充本节结论的独立卡片及原书依据。
托管平台分开应用与设施补充本节结论的独立卡片及原书依据。
运行时环境
请求由前端选择服务器,沙盒限制OS与资源访问,Java6/Python2.5是历史运行时。实例可能复用以降低启动成本,但无会话亲和或持久内存保证,库能否使用仍取决于所需能力。
沙盒约束补充本节结论的独立卡片及原书依据。
平台可保留应用实例和预加载运行时,以减少每次启动成本;同一实例的全局或静态变量因此可能复用。实例也可能被回收,来自同一用户的请求还可能落到不同服务器。只适合丢失后可重建的初始化缓存,不能把进程内变量作为会话或业务持久状态的唯一来源。
实例内存适合缓存所有请求共用的解析配置等可重建数据;同一用户后续请求不保证落在此实例,实例也随时可被清除。可靠状态放持久层,跨实例临时副本用memcache,仍不能当永久真值。
实例复用不保证请求亲和补充本节结论的独立卡片及原书依据。
书中Java6 JVM及Python2.5运行时允许各自生态中的部分语言、框架和库,但能被解释或编译不等于所有功能都可用。调用需要沙盒外部能力的库仍会失败。选择依赖时核对实际需要的文件、网络和系统能力,而不只看语言名称或声称兼容某个运行时。
Python依赖还须为可在目标解释器运行的纯Python模块;随应用上传C扩展并不能绕过当时运行时限制。
Java类进入白名单也不代表其全部方法可用,例如Thread可用于观察当前线程但不能据此创建新线程;JNI不支持,自定义类加载器也不提升权限。
库兼容还要检查沙盒能力补充本节结论的独立卡片及原书依据。
GWT允许用Java编写富Web应用的界面和应用代码,并把界面交付给浏览器运行,原书以无需浏览器插件说明其使用目标。它处理客户端开发方式,不代表任意Java服务器库都能在GAE沙盒中工作,也不把2010年的浏览器支持描述当作当前兼容清单。
GWT把客户端开发纳入Java补充本节结论的独立卡片及原书依据。
静态文件服务器
静态资源不需每次执行应用逻辑,由独立静态文件服务器处理;上传时一并交付,配置URL、内容类型及浏览器缓存时间。
图片、CSS、浏览器脚本和静态HTML可由静态文件服务器直接发送,不必为每次读取启动应用处理器。上传时把资源与代码一起交付,再明确URL映射、内容类型和浏览器缓存时间。静态分流改变处理路径,并不表示客户端不再需要正确的缓存与更新策略。
静态资源与动态执行分流补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
数据存储区
数据存储服务独立于请求执行,实体由kind、键和属性构成。同kind实体不强制同属性或同类型,属性可多值;键作为独立身份固定不变,应用仍须维护数据契约。
实体建模补充本节结论的独立卡片及原书依据。
键是实体的独立标识,不是某个普通属性;kind是其类别。两者在实体创建后固定,修改业务属性并不等于修改身份。知道完整键可以直接读取实体,属性值查询则走另一条访问路径。建模时分清稳定引用与可修改数据,不依赖同kind推定实体落在同一台机器。
键还含应用范围以区分数据;已知完整键可以直接取实体,键也能作为其他实体属性中的引用。实体类别与名称都参与身份,不应只比较一个键名字符串。
实体身份与属性分开补充本节结论的独立卡片及原书依据。
查询和索引
查询通过预先维护的索引访问匹配范围,不把原书表扫描译法误读成全实体表扫描。索引按查询形状声明,本地生成只覆盖实际演练路径,索引加快读取也增加写入和空间成本。
索引驱动查询补充本节结论的独立卡片及原书依据。
开发服务器观察实际执行过的查询并生成索引配置,上传后平台据此建立复杂查询所需索引。它能减少手工编写,却不会替未执行的代码路径证明查询覆盖。发布前应列出真正会出现的过滤和排序形状,核对配置与索引建立状态;不能只因开发环境测试通过就断言所有查询都可执行。
开发服务器只能为实际执行过的查询补配置,线上缺失会报错;工具不知道旧索引何时不再需要,删除前须检查所有仍服务的代码版本。
生成索引配置只反映已测路径补充本节结论的独立卡片及原书依据。
索引预先按查询需要组织数据,让读取能够直接寻找匹配范围。代价是索引占空间,实体创建或修改时还要维护相关索引,一个属性改动可能触及多个索引。评估索引时同时看读取路径和写入负担,不把“加索引”视为无成本的性能选项。
无关属性变更不一定触发某单属性索引变化;但额外索引仍占存储并可能增加相关写入负担,应按实际查询形状维护。
本节说索引应用可并行,不代表增加索引没有存储、CPU或维护成本;应与第5章冗余索引及MVP组合成本一起理解,不能只用墙钟并行推导免费写入。
索引读取收益伴随写入维护补充本节结论的独立卡片及原书依据。
事务
单实体更新具有原子性,多实体事务需预先组织实体组。乐观并发发生冲突后必须重新读取、计算和提交整个事务;组内热点会增加冲突,不能无限重试或把读操作当作永不失败。
实体组事务补充本节结论的独立卡片及原书依据。
乐观并发让冲突事务失败后由应用重新尝试。正确的重试单位是完整事务:再次读取最新状态,重新计算,再保存和提交;只把上次算出的旧值重写一次,无法表达同一业务计算。重试应有界,热点争用可能持续失败。这里的数据读取一致性说明不代表网络、权限或服务调用永远不会出错。
冲突重试要重新读取计算补充本节结论的独立卡片及原书依据。
服务
服务将特定能力放到请求运行时之外。memcache是可失缓存;URL Fetch异步调用仍受当前请求寿命约束;Mail和XMPP把入站消息转换为HTTP处理,图像服务只作为托管能力示例。
memcache以非持久键值缓存换取快速访问,适合保存可重新得到的查询或计算结果。应用先读缓存,缺失后回到原数据或重新计算,再填回缓存;缓存丢失不能意味着业务状态丢失。分布式共享缓存与某个实例的全局变量不同,也不能拿缓存接口直接代替持久数据事务。
时钟示例把用户偏好持久保存在数据存储区,memcache只作次要副本;缓存查无结果时从持久层恢复。展示时间和提交偏好由不同处理器承担,便于分开只读显示与写入路径。
缓存不能作重要数据的短期主存储;即使本次set成功,后面也随时可能缺失。适用性取决于能否重建及容忍多旧,而不只是这个值是否会重复访问。
缓存缺失必须能够重建补充本节结论的独立卡片及原书依据。
本书的URL Fetch允许请求处理器发起异步HTTP获取,在等待远端响应时做其他工作;启动与完成仍须处在同一请求处理器的生命周期内,并受截止时间限制。异步减少等待期间的阻塞,不等于产生一个可独立存活的后台任务;需要脱离请求的工作应使用对应任务机制。
若发起make_fetch_call后立即get_result且无独立工作,效果与同步相近;要获得收益须尽早发起并把可独立计算或多个外取重叠,最后仍在处理器生命周期内收取结果。
异步外取仍受请求寿命约束补充本节结论的独立卡片及原书依据。
在本书的GAE服务模型中,应用通过Mail或XMPP服务接口发送外部消息;收到发往应用的消息时,平台再调用对应HTTP处理器来转交内容。应用因而可以复用请求处理方式,但消息来源、解析与业务结果仍需分别处理。这里只描述历史接口,不表示当前平台仍提供相同服务。
入站消息转成HTTP处理补充本节结论的独立卡片及原书依据。
托管平台分开应用与设施补充本节结论的独立卡片及原书依据。
GAccount
GAccount可复用既有账户,Apps组织成员可用同一身份访问定制应用;开发者也可选择自建或其他身份提供方,不把统一账户等同于所有应用权限。
应用可复用平台账户,让已有用户无需另注册一套身份;组织应用也可用同一账户接入邮件、日历和自定义服务。这是身份复用方式,应用仍需明确自己的访问规则。GAE并非只能采用GAccount,原书还保留了自建账户或其他身份提供方的选择。
共享账户减少重复身份补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
任务队列和计划任务
任务队列把工作移出用户同步等待路径,以HTTP处理器执行并对失败重试;事务型排队连接提交与后续工作。cron按时间触发处理器,二者不等同于长驻后台进程。
任务队列补充本节结论的独立卡片及原书依据。
在本书支持的事务型排队中,只有数据存储事务成功,任务才会进入后续队列。它把提交结果与后续工作的产生联系起来,避免事务失败却先执行后续任务;但消费者执行仍是异步阶段,不能把整个后续流程宣称为同一个同步原子事务。
事务入队将原实体提交和后续工作记录绑定,任务执行仍在原事务外,产生最终一致窗口,并非把多个组同时放进一个全局强事务。该功能在书写时尚未发布,原文未提供API示例,不据此补造历史可运行接口。
事务排队连接提交与后续处理补充本节结论的独立卡片及原书依据。
cron服务按上传的时间计划调用应用请求处理器,适合日常维护或定期提醒;队列则主要承接应用产生的待办工作。二者都利用处理器执行,计划触发时间、队列速率和处理完成时间是不同概念。这里只记录原书的历史服务组织,不创建任何真实定时任务。
计划任务按时触发处理器补充本节结论的独立卡片及原书依据。
开发人员工具
SDK提供本地模拟Web服务器、热重载、调试及索引配置辅助,也有与线上应用交互的上传、日志、索引和远程数据工具;同一SDK包含不同作用域,不把本地测试当作线上验证。
开发Web服务器在本地模拟运行时、数据存储与服务,侦测代码修改并重载。Java可从Eclipse调试入口设置断点,Python也可借助PyDev接入交互调试。模拟环境便于验证应用路径,不证明线上配额、性能和所有限制相同;测试索引完整性时还需关闭自动生成来观察缺失配置。
按原书入门流程,可以先下载相应语言SDK进行本地开发,在线应用的账户与上传步骤另行配置。本地运行成功不等于已获得线上应用管理权限。
开发模型分为创建应用、本地开发服务器测试和线上上传;注册应用ID与域名属于后续部署阶段,不与单纯运行本地程序混为一步。
SDK模拟与线上运行分开补充本节结论的独立卡片及原书依据。
SDK不仅能运行本地应用,也能上传代码、下载线上日志、管理线上索引或远程访问数据。Python SDK的批量工具和交互Shell还可借远程访问功能作用于Java应用。先明确目标应用、环境和读写对象,再选工具;工具来自开发SDK,并不意味着操作只发生在本机。
原书Python SDK的数据工具用于备份、数据结构转换和离线处理;Java应用可在具备远程访问功能后利用这些工具。它们改变的是在线应用数据,不因为工具随本地SDK分发就变成模拟操作。
SDK维护入口先辨作用域补充本节结论的独立卡片及原书依据。
管理控制台
管理控制台以管理员身份管理应用、观察日志与资源,并区分上传版本、非默认版本测试和默认版本切换。预算按资源分配,实际付费按当时规则扣除免费资源,不作为当前收费依据。
控制台管理员可以查看和管理应用,还能上传应用版本;应用自己的终端用户则通过业务入口使用服务。都使用GAccount并不使两种角色等价。给其他账户增加管理资格时,要按其能够触及的部署、日志和数据能力理解授权范围,不把普通登录当成管理员许可。
管理身份不同于应用用户补充本节结论的独立卡片及原书依据。
上传代码时配置中的版本标识用于区分部署版本。原书允许经专用版本URL测试非默认版本,再由控制台改变默认版本来影响正式入口。上传成功、测试通过和默认流量切换是三个阶段;也不能仅凭代码可回切就推断数据变更已自动回滚。
上传版本不等于切换默认补充本节结论的独立卡片及原书依据。
原书的付费账户设置按日预算,并在预算内分配CPU时间、带宽、存储和邮件收件人等资源。预算与配额是控制边界,实际付费还取决于使用和当时免费额度。不同资源有各自单位,不能把预算设置值当成已经消费的数额;这些历史规则不作为当前价格或硬性费用保障。
预算只是历史资源购买上限而非预充值,账单按实际使用生成;CPU小时、带宽GB、存储GB日和邮件收件人数单位不同。价格、免费档和预算是否硬停用必须按目标时期核验,不能把本书2010年账单承诺迁作当前服务保证。
预算分配不同于实际消费补充本节结论的独立卡片及原书依据。
资源计费不等于容量承诺补充本节结论的独立卡片及原书依据。
App Engine暂时还做不到的事情
本节列举当时HTTPS、域名、消息地址、后台执行、持续连接和全文搜索的能力缺口。保留具体历史条件及设计影响,避免把缺口清单当成当前平台状态或推荐绕过安全检查。
原书区分appspot子域名、自定义域名与消息收件地址,并列出当时HTTPS、裸域名和多级域名的限制。Web入口可用某个域名,不代表邮件、XMPP或安全连接也能用同一个名字。部署前按入口类型和具体版本核对,不能把2010年的域名支持矩阵沿用到当前环境。
域名与端点能力逐项核对补充本节结论的独立卡片及原书依据。
原书列出当时URL Fetch可发HTTPS请求却不验证远端证书,这是对端身份核验的缺口。能建立加密传输,不等于已经确认连接对象可信。这里保留的是历史限制及其含义,不把“不验证证书”作为安全操作建议,也不据此描述当前平台行为。
第10章明确历史URL Fetch HTTPS接受任意证书,缺少信任链验证,故加密通道仍可能遭中间人攻击;这只描述原书旧服务,不能代替目标版本证书验证行为的核验。
加密传输还需验证对端补充本节结论的独立卡片及原书依据。
若5000个客户端各每5秒轮询一次,均匀分散时平均约为每秒1000个请求。缩短轮询间隔或增加客户端都会放大负载;如果触发时间集中,峰值还可能更高。这是按请求频率的推算,不是平台实测吞吐,也不意味着每个请求都必定对应一次数据库查询。
轮询频率会放大后端负载补充本节结论的独立卡片及原书依据。
按属性值过滤和排序的索引,不等于按词项匹配文本的全文搜索。原书的早期数据存储不为长文本建立普通属性索引,也未提供所述全文搜索能力;自行建立搜索索引还需处理数据更新和扩展成本。本节没有展开具体算法,因此不补造分词或索引实现。
属性索引不等于全文搜索补充本节结论的独立卡片及原书依据。
任务队列补充本节结论的独立卡片及原书依据。
沙盒约束补充本节结论的独立卡片及原书依据。
原书依据 · 11 处
- 第1章 GAE简介 App Engine暂时还做不到的事情 · 查看原书依据
- 第1章 GAE简介 App Engine暂时还做不到的事情 · 查看原书依据
- 第10章 获取URL和Web资源 第10章 获取URL和Web资源 · 查看原书依据
- 第1章 GAE简介 App Engine暂时还做不到的事情 · 查看原书依据
- 第1章 GAE简介 App Engine暂时还做不到的事情 · 查看原书依据
- 第1章 GAE简介 任务队列和计划任务 · 查看原书依据
- 第1章 GAE简介 App Engine暂时还做不到的事情 · 查看原书依据
- 第13章 任务队列和计划任务 第13章 任务队列和计划任务 · 查看原书依据
- 第1章 GAE简介 运行时环境 · 查看原书依据
- 第1章 GAE简介 App Engine暂时还做不到的事情 · 查看原书依据
- 第3章 处理Web请求 沙盒 · 查看原书依据
第2章 创建一个应用程序
第2章把应用从项目文件推进到本地测试、注册、部署与线上观察。Python以app.yaml和webapp分派,Java以WAR、Servlet描述符与平台配置分工;两者用稳定用户ID保存偏好并加入可丢失缓存。模拟登录、代码版本与共享服务配置、路由权限、持久化与缓存双写各有边界,不能把本地页面能打开当作线上正确性证明。原书示例的排版损失、Java文字与代码不一致、调试开关假设已在对应卡片标明。
第2章 创建一个应用程序
第2章按创建、本地测试、在线注册与上传的流程展开,并以用户偏好保存为贯穿示例;本章导言不代替后续两种语言的实际过程。
SDK模拟与线上运行分开补充本节结论的独立卡片及原书依据。
安装SDK · 连续片段1
完整读完Python SDK安装、平台分发形式、命令入口及Launcher操作。版本以Python2.5为目标,原文命令排版丢空格不可原样复制;安装路径发现、脚本关联、本地运行和在线部署分开。图2-1已实读。
本地解释器或编译器能运行某段代码,不说明目标平台也支持同样语言和库特性。原书的Python运行时为2.5,本地SDK虽可用2.6,开发仍应对照目标版本以减少差异。检查构建工具、运行时及依赖各自版本,而不只确认机器上“已经安装Python或Java”。这是历史版本示例,不建议据此配置当前系统。
历史Mac章节还要求匹配处理器位数、Java版本与Eclipse版本;“系统自带Java”只适用于当时列举的OS版本,不能代替对当前实际工具链的检查。
开发版本应匹配目标运行时补充本节结论的独立卡片及原书依据。
原书按Windows安装包、Mac应用包或其他平台ZIP分发SDK,并使命令行工具可被找到。典型检查入口是python -V和dev_appserver.py --help:前者核对解释器,后者确认SDK启动脚本能被调用。原文命令中分隔空格排版丢失,正文补出正常分隔;这些命令未在本轮运行,也不是当前平台安装指南。
Python工具安装后核对入口补充本节结论的独立卡片及原书依据。
“命令找不到”先核对SDK是否解压或安装、命令目录是否进入PATH;Windows不能识别.py文件的打开方式,则是脚本与解释器关联的问题。Mac的命令符号链接也有自己的目标路径。先辨明失败发生在哪一层,再处理对应入口,不要把所有启动失败都归因于没有安装SDK。
命令发现与脚本关联分开排查补充本节结论的独立卡片及原书依据。
历史Launcher先创建项目目录和初始文件,再对所选项目执行Run/Stop;Browse、Logs和SDK Console观察本地应用及模拟数据,Edit进入项目文件。Deploy用于上传线上应用,须先注册应用ID并写入配置,Dashboard进入线上管理。操作前确认所选项目与入口,避免把本地控制按钮和线上发布当成同一件事。
项目控制与线上部署分开补充本节结论的独立卡片及原书依据。
SDK维护入口先辨作用域补充本节结论的独立卡片及原书依据。
安装SDK · 连续片段2
Mac Launcher更新后符号链接可能失效,因为应用目录已改变且链接创建需另行许可;PATH与解释器关联不同,更新后要重新核对入口。
SDK升级可能改变实际安装目录,使原来的符号链接或PATH指向旧版本。原书Mac Launcher需重新创建链接,Eclipse内置SDK路径也带版本标识。入口修复后仍要确认调用到哪个工具版本;命令名字未变,并不说明底层程序未变。
Eclipse安装的SDK目录名包含版本号,更新后PATH可能仍指旧目录。应重新确认工具真实位置及脚本执行权限,而不是只保留原来的路径字符串。
SDK更新可能改变命令路径补充本节结论的独立卡片及原书依据。
安装Java SDK
完整读完JDK/本机位数与Eclipse版本匹配、Plugin和SDK分别安装、独立ZIP与启动脚本及Ant集成。图2-2⁄2-3已读;历史Mac自带Java的说法不作为当前机器前提。
JDK提供本地Java构建和运行基础,App Engine SDK提供其支持的Java EE接口实现。原书允许Java5或Java6构建,线上使用Java6 JVM;这不意味着平台实现了全部Java EE功能。按目标运行时和沙盒约束核对接口与依赖,不必因使用Servlet或JPA就另装一套完整Java EE服务器。
JVM字节码可来自其他语言编译器或解释器,但应用结果仍须实现Servlet接口并服从沙盒;能在一般JVM运行不等于必能在该平台运行。
JDK与平台接口实现各有职责补充本节结论的独立卡片及原书依据。
原书Eclipse安装流程分别选择插件和SDK,配置Installed JREs指向适用JDK,再利用插件创建Web项目、调试本地服务器或部署。独立ZIP安装则从SDK的bin目录调用启动脚本;javac -version核对编译器,dev_appserver.sh --help是原书Mac/Linux的SDK入口检查。图中版本与路径都是历史示例,未执行安装。
Java插件与SDK分别配置补充本节结论的独立卡片及原书依据。
Java SDK的命令启动脚本封装了相应Java类,集成IDE或自定义脚本时可按真实启动脚本核对调用方式;SDK还提供Ant插件,把相应功能接入构建任务。集成减少手工操作,不替代版本、类路径和目标应用的确认。本节未给出Ant配置,不补造构建脚本。
SDK功能可以接入构建流程补充本节结论的独立卡片及原书依据。
开发版本应匹配目标运行时补充本节结论的独立卡片及原书依据。
SDK更新可能改变命令路径补充本节结论的独立卡片及原书依据。
开发应用程序
应用配置把URL映射到处理器,并关联应用ID与代码版本;索引、队列和计划任务配置却属于整个应用。时钟示例分展示与提交处理器,持久偏好与可丢失缓存分层;不同服务器时钟不能当作同步保证。
应用ID和版本标识代码、应用配置与静态文件;本书的索引、任务队列和计划任务配置则关联整个应用。部署前分别列出随版本切换的内容和全应用共享的配置,测试版本可访问并不代表这些服务配置也被隔离。
索引配置也作用于应用所有版本,新版部署索引变化可能影响仍服务的旧代码;清理时不能只看当前开发分支。
第15章再次区分URL、运行时及入站激活的版本配置,与索引/队列/cron共享配置;非默认版本的部署也会改变共享服务配置,需单独评估发布影响。
update_indexes、update_queues、update_cron可只更新相应共享服务配置;部署新代码不是唯一改变服务行为的入口,回退代码也不会自动撤销这类独立更新。
服务配置不随代码版本隔离补充本节结论的独立卡片及原书依据。
不同服务器的内部时钟不保证同步,请求还可能被交给不同服务器。显示当前时间的小例子可以接受这种偏差;不能仅从每次读取服务器时间推导出跨请求严格单调、事件先后或分布式一致时间。后面这些限制是依据原文条件作出的推论。
服务器时钟不构成一致时间补充本节结论的独立卡片及原书依据。
缓存缺失必须能够重建补充本节结论的独立卡片及原书依据。
开发一个Python应用程序 · 连续片段1
Python最小项目以app.yaml关联运行时与处理脚本,CGI通过环境和标准流交换请求响应;webapp进一步按URL选RequestHandler并分派HTTP方法。源码排版空格与缩进丢失,未把示例视为可直接运行程序;调试自动关闭的书中说法单独核验并限定。四图已经实读。
app.yaml先决定哪个脚本处理URL,框架再在该脚本内按自身路由选择处理器。最小Python项目必须让配置中的应用、版本、运行时和script字段对应实际文件;CGI示例通过环境变量及标准输入取得请求,用标准输出发送响应头、空行和正文。摘录的缩进与分隔符有排版损失,配置应回到目标版本格式校验,不能直接粘贴扁平文本。
多数框架把动态URL统一交给自身调度器;示例为利用配置级登录验证又把/prefs交给单独脚本。两层匹配应协同,而不是无意重复或截断彼此路由。
配置入口与框架路由分层补充本节结论的独立卡片及原书依据。
本书webapp的MainPage继承RequestHandler并实现get(),WSGIApplication按URL选择处理器,再把请求和响应交给它。处理器设置响应头并写出正文;类的继承职责与URL配置各自独立。图只表达原例真实关系。
请求类按方法处理响应补充本节结论的独立卡片及原书依据。
原书声称webapp会在生产环境忽略debug=True;本轮核验到Google托管历史源码的另一个固定提交,却将debug直接传入异常处理并据此向响应写入堆栈。因此不能把“上线自动关闭”当作可靠保障,应在目标版本显式关闭调试并验证错误响应。外部源码提交不宣称与书中SDK1.2.5完全同版。
外部补充核验:Google托管webapp源码,2026-11-14读取;核对WSGIApplication.init/call及RequestHandler.handle_exception。
上线前显式关闭调试输出补充本节结论的独立卡片及原书依据。
开发一个Python应用程序 · 连续片段2
main保护与应用缓存分工、两层URL调度、用户API与登录跳转,以及UserPrefs模型和稳定用户ID主键均已读。模型构造不会自动持久化,模拟账户不等同真实身份认证。
本地开发服务器的GAccount模拟登录接受任意邮件地址,还可模拟管理员;它便于覆盖未登录、普通用户及管理员分支,但不验证真实账户所有权。线上登录跳转到真实账户服务后再返回应用指定路径,两种运行环境的身份保证不可混用。
Java开发服务器同样模拟任意邮件地址的登录,本地账户分支测试不能代替真实账户服务与线上授权验证。
模拟登录不能证明真实身份补充本节结论的独立卡片及原书依据。
原书Python users.get_current_user()在未登录时返回None,登录后返回User。create_login_url()/create_logout_url()生成入口并指定完成后返回的应用路径;它们生成URL,并不直接把当前请求变成已登录。页面应根据当前状态展示入口,写入路径另行强制认证。
Java对应UserServiceFactory.getUserService()、getCurrentUser()及createLoginURL()/createLogoutURL();未登录返回null。它与Python承担相同身份状态和返回路径职责,但接口名、空值及配置不同。
用户状态与登录跳转分开处理补充本节结论的独立卡片及原书依据。
UserPrefs以账户user_id()作为键名,结合类别构造唯一实体键,已知身份即可按键读取,避免为每次偏好访问发起查询。返回的默认UserPrefs可能只存在于内存,调用者还须put()才能创建持久实体。不要把“构造对象”当成“保存成功”。
Java UserPrefs的@Id字段也用用户ID建立实体键,首次保存后不得修改;getPrefsForUser()找不到时只构造默认对象,save()才执行持久化。
稳定用户标识构造偏好主键补充本节结论的独立卡片及原书依据。
配置入口与框架路由分层补充本节结论的独立卡片及原书依据。
原书依据 · 8 处
- 第2章 创建一个应用程序 开发一个Python应用程序 · 连续片段2 · 查看原书依据
- 第2章 创建一个应用程序 开发一个Java应用程序 · 连续片段2 · 查看原书依据
- 第2章 创建一个应用程序 开发一个Python应用程序 · 连续片段2 · 查看原书依据
- 第2章 创建一个应用程序 开发一个Java应用程序 · 连续片段2 · 查看原书依据
- 第2章 创建一个应用程序 开发一个Python应用程序 · 连续片段2 · 查看原书依据
- 第2章 创建一个应用程序 开发一个Java应用程序 · 连续片段3 · 查看原书依据
- 第2章 创建一个应用程序 开发一个Python应用程序 · 连续片段1 · 查看原书依据
- 第2章 创建一个应用程序 开发一个Python应用程序 · 连续片段2 · 查看原书依据
开发一个Python应用程序 · 连续片段3
显示偏好表单与POST保存处理器分工清楚:解析整数后put,再重定向;示例为简化而吞掉非法输入,未推广为生产校验。配置要求登录且特定路径必须在通配路径之前。缓存代码引出先缓存后持久化的失败窗口。
本书app.yaml按顺序使用第一个匹配项。/prefs必须放在/.*前面,否则写入处理器及其login:required配置可能被兜底吞掉。配置访问权限时同时检查顺序、URL和实际处理器,不能只确认某段认证字段存在。
Python URL使用类似正则的模式,字面点号等须转义;/.*作为兜底应最后出现。Servlet模式不是Python正则,不把任意正则特性套入web.xml。
特定路由应先于兜底匹配补充本节结论的独立卡片及原书依据。
示例的GET只展示时钟与偏好,POST解析时区整数、保存实体后重定向首页,由新GET呈现结果。非法整数被忽略仅是教学简化;实际产品应说明失败并限制有效范围。重定向不会自行证明保存成功,须以写入结果决定后续响应。
Java PrefsServlet.doPost()使用request参数更新偏好,完成后sendRedirect(“/”);原文说明这可让后续刷新首页无需重发表单。示例忽略NumberFormatException是简化,不作为输入校验标准。
提交表单后重新读取页面补充本节结论的独立卡片及原书依据。
开发一个Python应用程序 · 连续片段4
memcache键、命名空间与对象序列化、读缓存回源及日志观察均已读。重写put先缓存再写数据库的示例存在明确双写失败窗口,记录为示例边界,不作为一致性保证。
示例UserPrefs.put()先cache_set()再db.Model.put(self)。若第二步失败,其他读取者仍可能从缓存看到未持久化的新偏好;因此双写顺序不提供原子性。这是依据示例控制流推导的失败窗口,原书没有给出完整修复协议。设计时须明确持久层真值、写失败处置及并发旧值回填策略,不能只添加缓存而忽略失败分支。
Java段落也承认缓存与数据存储区不能保证同时成功,并提出先持久化、再更新缓存及设置过期时间。过期可以限制某些残留旧值的持续时间,却不等于两服务原子提交;并发回填和失败场景仍须设计。
缓存先写会暴露未落库状态补充本节结论的独立卡片及原书依据。
本例把用户ID作为memcache键,把UserPrefs类别作为命名空间,从而区分不同业务对象。memcache API序列化对象,缓存未命中则回持久层,找到才回填;两处都没有时构造默认对象。可用开发日志观察cache_set调用,日志只能证明调用发生,不能证明缓存永久存在。
namespace是键独立部分,所有读写都须一致指定;key_prefix仅给批量键拼公共字符串,get_multi返回键又去掉此前缀,两者不能互换。
缓存键还要划定命名空间补充本节结论的独立卡片及原书依据。
开发一个Java应用程序 · 连续片段1
Java通过Servlet标准处理请求,WAR是实际部署内容;src编译与资源复制到WEB-INF。web.xml负责标准路由,appengine-web.xml负责平台身份,相关SDK JAR也必须在WAR。图2-8已读。
原书Java项目把源码放src,部署内容放war;已编译类进入WEB-INF/classes,依赖JAR进入WEB-INF/lib,资源也要复制到最终位置。手工或自动构建都应检查WAR,而不只是源码目录存在。开发工具自动复制是构建行为,不是线上平台替你补齐缺失产物。
部署目录应包含最终构建产物补充本节结论的独立卡片及原书依据。
web.xml定义Servlet类与URL映射;appengine-web.xml定义App Engine应用ID、版本及平台专有选项。ClockServlet继承HttpServlet并重写doGet,读取HttpServletRequest、写入HttpServletResponse。标准接口可复用,但仍须补齐目标平台配置与实现依赖。
标准描述符与平台配置分工补充本节结论的独立卡片及原书依据。
开发一个Java应用程序 · 连续片段2
Java本地启动针对WAR,用户服务工厂提供平台身份API,而Servlet Principal提供可移植但不完全等价的标准接口;JPA/JDO仍受底层存储能力限制。
Servlet的getUserPrincipal()可返回标准Principal,便于移植;平台UserService则暴露专有身份功能。标准接口不一定覆盖平台所有能力,平台也可能只实现标准的一部分。JPA/JDO同样是访问层,采用标准名字不意味着底层就具有关系数据库的所有语义。
JDO/JPA将类、对象、字段映射为类别、实体、属性,仍有不能直接对应的元素;动态属性名或类型未知时可选低级Entity API。对象接口可移植性不替代底层语义核对。
JPA/JDO在这里经DataNucleus适配底层存储,只支持可映射的标准子集;从传统关系库迁入可能需要改变查询和事务假设,不能因使用同一接口就承诺双向无修改迁移。
标准接口不能抹平平台差异补充本节结论的独立卡片及原书依据。
用户状态与登录跳转分开处理补充本节结论的独立卡片及原书依据。
模拟登录不能证明真实身份补充本节结论的独立卡片及原书依据。
开发一个Java应用程序 · 连续片段3
JPA配置指定持久化实现及持久化单元,工厂复用而EntityManager按使用创建并finally关闭;实体标注和构建增强让对象具备持久化能力。UserPrefs仍以稳定用户ID为不可变键。
示例静态EMF包装器保存EntityManagerFactory,避免反复初始化工厂;每次操作再创建EntityManager,并在finally关闭。工厂生命周期与一次数据访问上下文不同,不应因为工厂可复用就把所有访问状态混在一个长期共享上下文里。
持久化单元名用于选择配置,NontransactionalRead/Write允许事务外操作,不表示一组操作自动原子。昂贵工厂可复用,每个请求的EntityManager另管理与关闭。
每个请求创建自己的EntityManager并在结束时关闭;关闭前应完成所需惰性加载及事务处置。构造上下文若失败,清理代码也不能调用未初始化引用,本书简化片段未直接执行。
持久化工厂与上下文分开管理补充本节结论的独立卡片及原书依据。
本书JPA实体用@Entity/@Id/@Basic声明映射,编译后由增强步骤修改字节码,补入持久化调用。Eclipse插件可自动完成,其他构建流程须显式接入SDK工具或Ant插件。只有标注和.class文件存在,并不足以证明该历史实现所需的增强已经完成。
DataNucleus在编译后附加持久化代码;未用自动插件时须把增强加入实际构建流程,不能只拷贝persistence.xml。
标注之外还需完成构建增强补充本节结论的独立卡片及原书依据。
稳定用户标识构造偏好主键补充本节结论的独立卡片及原书依据。
开发一个Java应用程序 · 连续片段4
Java POST处理器解析、保存再重定向,web.xml安全约束单独限制/prefs。Servlet映射按更具体模式优先,不能套用Python顺序规则。叙述把EntityManager误称PersistenceManager,按实际JPA代码区分。
Python app.yaml示例按首个匹配项决定处理器;Java web.xml本节则按模式具体程度匹配,非通配部分较长者先。Java的security-constraint又单独指定受保护URL。迁移路径配置时,须一起核对匹配算法、Servlet映射和认证约束,不能机械照抄另一个运行时的顺序规则。
路由规则必须按配置体系核对补充本节结论的独立卡片及原书依据。
提交表单后重新读取页面补充本节结论的独立卡片及原书依据。
开发一个Java应用程序 · 连续片段5
Java缓存示例实现Serializable并查缓存、回源、补缓存。代码使用UserId,文字却说邮箱;文字称save同步缓存,但展示代码只persist。contains后get仍有淘汰窗口,不能推断缓存必有值。
本节Java示例缓存键实际为”UserPrefs:“加getUserId(),后文却称加电子邮件地址;文字还说save()更新缓存,展示的save()只调用em.persist(this)。阅读时按真实控制流分别记录,不能把未出现的cacheSet()调用当成已实现功能。本轮未运行或补写该历史例程。
示例代码与文字不一致须标明补充本节结论的独立卡片及原书依据。
示例先memcache.contains(cacheKey)再get(cacheKey)。缓存可能在两次调用之间被淘汰,因此前一步为真不保证后一步返回对象。此为依据可淘汰缓存与示例控制流的推论;读路径仍须把get的缺失结果纳入回源分支,不能因contains成立就直接返回null。
先查存在仍可能读取缺失补充本节结论的独立卡片及原书依据。
缓存先写会暴露未落库状态补充本节结论的独立卡片及原书依据。
开发控制台
本地控制台可操作模拟实体、缓存、运行临时代码、手动任务与模拟消息。交互查询也可能改变索引配置;本地控制台不是只读监视器。图2-9已读。
本书本地/_ah/admin包含实体及缓存编辑、交互Python执行、任务运行与删除、模拟消息发送。交互查询还可能自动写入index.yaml;任务队列在该开发服务器中需手动触发。调试前区分只查看、改模拟数据和改项目配置,测试结果也不能当成线上队列已自动执行。
开发控制台操作会改变状态补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
注册应用程序
注册开发账户和唯一应用ID是上传前提,标题是用户可见名称。十应用、短信流程及删除等待均为历史操作,不推广为现行规则;图2-10已读。
应用ID用于配置、部署及默认域名等身份关联,应用标题供控制台与登录页向用户展示。原书注册后ID不可改而标题可改;使用教程的clock示例前须替换为实际已注册ID。平台历史注册额度与验证流程需另查目标环境,不能用教程名称直接部署到别人的应用。
设置面板的标题、登录cookie时长与服务激活各自作用不同;标题可改并不代表应用ID或原书注册时认证策略也可改,操作前应核对具体字段。
应用标识与展示标题分开补充本节结论的独立卡片及原书依据。
设置域名
自定义域名依赖当时Apps关联及DNS指向;子域名绑定、根域重定向与已有Sites占用是不同配置。只记录历史操作边界,不购域名或改DNS。
本书流程通过Apps将子域名绑定到应用,并用DNS指向服务;根域example.com的HTTP请求另行跳转到www,www若已由Sites占用还需先解除。应用已绑定子域名,不意味着根域、TLS或其他服务占用已一并处理。这些平台步骤限定于书中历史环境。
默认appspot.com额外子域与Apps自定义域规则不同,不应把一套域名上的映射能力直接套给另一套。
域名绑定与根域跳转分开补充本节结论的独立卡片及原书依据。
Apps和身份验证
组织域登录限制只影响GAccount认证,不自动保护公开URL;平台注册身份、应用登录身份仍有区别。
原书的Apps身份限制只在使用GAccount认证时生效;不要求登录的欢迎页等仍可被公众访问。需要保护的路径必须另加login:required或Servlet安全约束。开发账户能进入管理控制台,也不代表它满足应用自己的组织域限制。
登录域限制不自动保护公开URL补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
上传应用程序
上传命令读取配置中的ID和版本;Python针对项目目录、Java针对WAR。部署副本不能替代源码与构建产物备份,本轮未执行上传。
本书Python命令appcfg.py update clock中的clock是目录,Java appcfg update war中的war是部署目录;工具从各自配置读取应用ID与版本。提交前核对目标,而不是把目录名当应用身份。原书还警告不能从服务端下载回应用文件,因此版本控制及备份要独立保存源与构建所需材料。
第15章再次强调Java命令以WAR为上传内容,Python以app.yaml所在目录为目标,上传后无法下载源文件的历史限制使独立版本控制和备份成为必要准备。
上传前核对目录身份与备份补充本节结论的独立卡片及原书依据。
管理控制台简介
线上仪表板汇总请求、延时、错误及各类资源,图表自动缩放会把少量访问画成满幅尖峰;版本测试、配额与日志需结合解释。图2-11已读。
原书仪表板请求图按区间内最高值自动缩放,少量测试请求也可能产生顶到图框的尖峰。判断负载应读坐标单位、时间窗口、请求率与错误率,并结合配额及资源使用量;仅凭曲线很高不能证明接近系统容量。
图表高度不能代替绝对负载补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
第3章 处理Web请求
第3章沿一次请求从前端走到静态服务器或应用实例,再进入共享服务。路由、传输安全和账户授权分层配置;代码版本可以并存,却不天然隔离后台数据。实例缓存降低重复初始化成本,但不保证持久性或用户亲和,Java还需处理容器并发。日志把请求、延时、CPU和错误关联起来,配额、单次调用体积与部署边界则约束工作如何拆分。最后的付费配额和资源响应头说明资源预算、实际消耗与单次估算应分开解读,具体收费模型保持历史范围。
第3章 处理Web请求
请求越短越便于调度与扩展,也减少故障时在途请求数。本章将依次沿请求路径展开路由、静态文件、HTTPS和运行时复用,延时目标限定书中平台。
在相同到达速率下,单次处理时间越长,平均在途请求通常越多;机器故障可能中断的工作也随之增加。原书用每秒100请求、10毫秒和100毫秒对照,说明减少响应必要工作可同时改善体验、调度与故障影响。该比较依赖相同负载等条件,不是平台容量基准。
缩短请求减少在途故障暴露补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
App Engine的架构
请求从负载均衡和前端进入,按域名找应用、按路径分静态或动态、必要时先鉴权;应用服务器在沙盒中调用共享服务并在处理结束后返回完整响应。App master负责部署,切换默认版本仍允许旧在途请求完成。图3-1已实读。
早期GAE前端按域名和路径选择应用及处理目标,可先执行访问控制。静态请求走专用文件服务器,动态请求交应用实例;实例以受限API访问共享存储等服务。运行时隔离本机资源,服务才提供跨实例共享状态。图中各节点代表集群,不是各一台机器。
前端分流与应用服务各有边界补充本节结论的独立卡片及原书依据。
原书默认版本切换后,切换前已启动的请求仍可由旧代码完成。因此不能把切换时刻视为全系统瞬间只剩新代码;应用向自身发HTTP请求时尤其要考虑跨版本交互。代码和数据协议的兼容边界应覆盖这段并存窗口。
切换版本不终止旧请求补充本节结论的独立卡片及原书依据。
书中运行时等处理器结束后才发送完整响应;向输出流多次写入只是构造缓冲内容,不能据此实现持久连接或持续推送。长工作需按任务等机制拆分,而不能靠提前写出少量正文绕过请求寿命。
缓冲响应不等于流式连接补充本节结论的独立卡片及原书依据。
对前端进行配置
app.yaml在项目根目录定义序列、映射与运行时版本,缩进和序列顺序有语义。摘录扁平化不能当有效YAML,版本声明用于在兼容变更前明确目标。
YAML用缩进表达范围,序列顺序有意义而映射键次序通常不表示处理顺序。app.yaml须在应用根目录;runtime和api_version表达书中运行时选择。修改前同时核对结构解析与目标版本,不要因字段拼写看似正确就忽略缩进或错误的版本假设。
配置格式与目标版本同时校验补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
配置Java应用程序
WAR布局与两种XML描述符再次明确;API版本由应用携带的API JAR识别,平台可换成兼容实现。配置校验架构来自实际SDK。
标准描述符与平台配置分工补充本节结论的独立卡片及原书依据。
域名
默认域与Apps自定义域有不同子域支持;Host可作为路由输入,不能未经验证直接当身份授权。根域跳转与子域绑定已并入前卡。
原书appspot.com支持额外单个域名段,应用可从Host头辨认所请求的域名,从而区分站点入口。Apps自定义域不具有完全相同的规则。这里的Host是请求路由信息;将其用于租户选择还须核对允许域和授权关系,不能只凭客户端提供的字符串判定用户权限。
请求域名可参与应用路由补充本节结论的独立卡片及原书依据。
域名绑定与根域跳转分开补充本节结论的独立卡片及原书依据。
应用程序的ID和版本号
版本ID区分文件与前端配置,但不同版本共用存储、缓存、服务与资源;可访问测试域不代表独立环境,版本URL也不自动保密。历史10版本额度不作当前承诺。
本书同一应用的多个代码版本访问相同数据存储、memcache及其他服务,并共享资源。dev/live名称只分代码与前端配置,测试写入仍可能影响正式数据。隔离测试不能只创建一个新版本号,还须设计数据、缓存键及外部副作用的边界。
测试版本仍共用后台状态补充本节结论的独立卡片及原书依据。
原书各上传版本都有专用URL,知道应用ID和版本号者可能直接访问。可用前端账户授权限制开发版本;只在应用代码检查Host不能覆盖直接由静态服务器交付的文件。没有设为默认版本,不等于该版本对外不可见。
版本页面列出的Live URI可直接访问,版本ID不是秘密授权机制;观察日志和使用率时还需确认左上选择的是哪个应用与版本。
非默认版本也需要访问控制补充本节结论的独立卡片及原书依据。
请求处理器
Python正则路由与Servlet模式不同,Servlet声明、初始化参数和映射分工明确;JSP部署时编译且可显式映射,JSTL由平台提供避免重复冲突。原XML中url-mapping与缺闭标签不作可运行范本。
web.xml的servlet声明给出引用名、实现类和可选init-param;servlet-mapping通过servlet-name关联到url-pattern。同一实现类可按初始化参数配置多个声明。原文某片段把url-pattern写成url-mapping,不能直接照抄;应按真实描述符规范与SDK校验结果处理。
Servlet声明与映射补充本节结论的独立卡片及原书依据。
本书JSP在上传阶段编译成Servlet,应用服务器执行编译结果;默认按文件路径映射,也可用jsp-file声明自定义入口。JSTL已由平台提供,重复打包可能引发版本冲突。动态模板即使像HTML,也不是直接交付的静态文件。
JSP编译与请求执行分开补充本节结论的独立卡片及原书依据。
特定路由应先于兜底匹配补充本节结论的独立卡片及原书依据。
静态文件和资源文件 · 连续片段1
静态文件用于直接交付,资源文件供应用读取,两者在Python默认互斥;static_dir与static_files的URL映射和上传集合职责不同。MIME及缓存过期由响应配置给出,版本化URL用于内容更新。
本书静态文件部署到专用服务器,Python应用不能再通过本机文件系统读取;模板等供应用读取的文件属于资源文件。若历史SDK需两用,可用两个部署名称上传两份并计入文件限额。Java默认行为另有规则,不能用一个运行时的文件可见性推断另一个。
静态交付与本机资源读取分开补充本节结论的独立卡片及原书依据。
Python static_dir直接把目录及子路径映射到URL;static_files可用正则分组重写文件路径,但另需upload模式指出本地哪些文件应上传。URL路由模式与本地文件筛选是两件事;mime_type可覆盖后缀猜测的响应类型。
静态映射还需定义上传集合补充本节结论的独立卡片及原书依据。
default_expiration指定默认缓存时长,处理器expiration可覆盖它;客户端仍自行决定是否遵从。要在长缓存期间发布新内容,可在资源URL中加入版本并随内容改变,让浏览器把它当成新资源。更改服务端文件本身不会强制已经缓存旧URL的客户端立即重取。
版本化URL配合静态缓存更新补充本节结论的独立卡片及原书依据。
静态文件和资源文件 · 连续片段2
Java默认文件可作本机资源,WEB-INF外非JSP还可静态交付;resource-files/static-files各自include/exclude控制两集合,MIME映射与expiration另配置。JSP源码叙述不作为公开源码建议。
Java的resource-files控制应用本机可读文件,static-files控制静态交付,两套include/exclude互不等同。排除大型图片的资源副本可减少实例加载量,但应用随后无法本机读取;敏感XML应检查静态排除,sitemap等例外单独包含。WEB-INF受特殊保护,不能直接变成静态集合。
资源排除规则应检查两套集合补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
安全连接
HTTPS由前端终止,按URL配置强制安全连接;书中自定义域和端口限制为历史边界。开发服务器忽略安全配置,因此HTTP本地通过不能验收TLS;证书告警也不作为可随意接受的正常步骤。
原书开发服务器不支持安全连接且忽略安全设置,故本地等价HTTP测试只能验证业务路径。线上还须验证目标域证书、HTTPS入口和跳转策略;域名不匹配的告警说明身份验证未满足预期,不应把点击继续当作验收通过。
本地HTTP通过不能验收TLS补充本节结论的独立卡片及原书依据。
Python处理器secure:always要求非安全请求改走HTTPS,optional允许两者;Java web.xml用user-data-constraint/CONFIDENTIAL约束传输。前端解密后再交给应用,处理器仍需独立执行身份和业务权限检查。HTTPS保护传输,并不自动授权用户访问资源。
传输约束与账户授权分别配置补充本节结论的独立卡片及原书依据。
通过GAccount进行授权
前端按已登录或管理员限制动态与静态资源;无规则默认公开,业务细粒度权限仍在代码。计划服务以受信身份访问端点的机制需与目标版本核对。
书中Python login:required/admin及Java auth-constraint的*或admin分别限制已登录用户与注册开发人员,既能保护代码也能保护静态资源。没有规则的路径仍公开;组织域限制不替代该规则,业务对象级授权也不由“已登录”自动完成。
前端粗粒度授权覆盖静态路径补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
应用程序是如何运行的
运行时包含解释器、内存、只读资源及服务API。CGI只是交换接口不规定每次重启解释器,Python实例可保留模块全局;请求环境每次重设,纯Python依赖限制与输出缓冲仍有效。
CGI定义用环境变量与标准流交换请求响应,并不必然要求每个请求启动新解释器。本书GAE预备解释器并可复用模块与全局内存;请求环境仍会重新设置。理解接口协议时要另查实例生命周期,不能从CGI这个名字推断启动成本或状态持久性。
请求接口不决定进程生命周期补充本节结论的独立卡片及原书依据。
本书APPLICATION_ID、CURRENT_VERSION_ID、AUTH_DOMAIN及SERVER_SOFTWARE提供应用、版本、身份域和开发环境线索,Python通过os.environ访问。实例可能复用但请求环境每次重置,不能把某次用户或环境信息永久缓存为所有后续请求的事实。
Java示例通过ApiProxy.getCurrentEnvironment().getAppId()/getVersionId()取得应用和版本;不要把Servlet描述信息、API环境与用户认证结果混为一类。
运行环境信息应按请求读取补充本节结论的独立卡片及原书依据。
库兼容还要检查沙盒能力补充本节结论的独立卡片及原书依据。
Java运行时环境
Java通过Servlet容器调用请求响应对象,其他语言可生成JVM字节码但仍须满足Servlet与沙盒限制;ApiProxy提供应用和版本环境。
JDK与平台接口实现各有职责补充本节结论的独立卡片及原书依据。
运行环境信息应按请求读取补充本节结论的独立卡片及原书依据。
沙盒
沙盒在解释器、JVM权限、白名单及替代实现多个层次限制进程、网络与文件;Java类可导入也不等于所有方法可用。JNI不可用,本地测试能覆盖部分限制。
早期GAE通过沙盒约束应用对操作系统与资源的访问:可读自己的程序文件,却不能据此把本地文件当可写持久存储;网络操作要走平台服务,请求还受时间、CPU和内存限制。隔离有助于多租户调度,但应用仍须设计状态与访问边界。原书30秒等具体限制属于2010年环境。
网络入口也受平台定义:本节描述的早期环境支持HTTP/HTTPS及特定消息服务,而不提供任意协议连接。不同端点的能力应分别核对,不从应用能发送HTTP推出能任意访问网络设备。
限制由多层执行:Python禁用部分标准库并以ImportError暴露问题;Java结合权限、JRE类白名单和替代实现。应用仅能读取自身资源,跨实例状态须走服务,不能靠观察同机进程或文件协调。
沙盒约束补充本节结论的独立卡片及原书依据。
库兼容还要检查沙盒能力补充本节结论的独立卡片及原书依据。
应用程序缓存
实例缓存保留模块、全局和静态数据但随实例丢失,适合共享不可变解析结果。Python main入口支持脚本复用仍需首次显式调用;import时机应先清晰后测量。Java并发请求要求共享状态线程安全,初始化顺序不等于部署时预热。
书中Python脚本首次由顶层分析并执行,后续可直接调用无必需参数的main()。因此既要定义main,又要在name为main时显式调用;只定义不调用会导致冷实例首个请求无响应内容而后续正常的间歇故障。此约定只对应书中历史处理器模型。
入口函数必须覆盖首次执行补充本节结论的独立卡片及原书依据。
已导入模块在同一实例内复用,顶层导入成本主要落在冷请求;滞后导入可避开不需要的模块,却在热路径也有检查开销。先按代码清晰度组织,再根据首请求实测决定是否延迟,不把所有import移入函数当作必然优化。
模块导入时机先清晰后测量补充本节结论的独立卡片及原书依据。
Java沙盒限制应用创建线程,却允许容器在同一JVM中并发执行多个请求。静态缓存、全局对象和初始化路径仍须线程安全;load-on-startup只指定加载顺序,本书仍在首请求时加载,不等于部署时已完成预热。
容器并发要求共享状态安全补充本节结论的独立卡片及原书依据。
实例复用不保证请求亲和补充本节结论的独立卡片及原书依据。
日志
请求日志含路径、域、状态、延时、CPU和响应大小,应用消息附日志级别;Python与Java标准输出语义不同。Java还需配置logging文件及系统属性,外部库适配影响级别保真。
平台请求日志覆盖动态、静态及无效URL,并记录状态码、响应大小、处理时间与CPU时间;应用日志再补关键事件及严重性。排障应把同一次请求的这些信息关联起来,不能只看单条错误或把等待外部服务的时间算成CPU工作量。
管理操作另有Admin Logs记录,如部署、权限、配置及控制台数据修改;应用请求日志不能替代管理员操作审计。
请求日志连接延时资源与错误补充本节结论的独立卡片及原书依据。
Python CGI的stdout构成响应,stderr按错误级别进日志;本书Java的System.out按info、System.err按warning记录,响应通过HttpServletResponse写出。调试打印前先确认接口,避免把日志混入页面或误以为Java stdout会发送给客户端。
标准输出语义取决于运行接口补充本节结论的独立卡片及原书依据。
本书Python用logging,Java用java.util.logging;Java七级映射到平台debug/info/warning/error,未捕获异常另记critical。Java logging.properties与java.util.logging.config.file共同决定门槛,外部库若只写标准流会损失原级别,应核对适配器是否调用平台识别的日志接口。
日志适配要保留级别映射补充本节结论的独立卡片及原书依据。
配额限制
每日配额与单请求寿命、体积等系统限制不同;书中30秒和10MB是历史值。即使捕获截止异常也须及时退出,异步来源的HTTP处理不自动豁免。
原书请求计时器将到期时抛出DeadlineExceeded类异常,可用于有限收尾或友好错误;继续不退出仍会被终止并返回系统错误。队列、cron、入站邮件和XMPP当时也受请求时限约束,不能把后台入口当成无限运行。书中30秒等数值不是当前配置建议。
请求截止异常只留收尾窗口补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
CPU限制
CPU分是历史归一化工作量而非墙钟时间,限流可能让同样CPU工作耗时更长;等待服务不消耗应用CPU。get_request_cpu_usage返回单位也不能混用,原书兆周期与浮点运算解释不推广。
同样计算在资源调度或限流下可能花费更长墙钟时间;等待服务返回又可能增加延时而不消耗应用CPU。原书计费CPU分与get_request_cpu_usage()返回的兆周期也不是同一单位。优化前分别测量计算、服务等待和总延时,避免把一个指标直接替代另一个。
CPU工作量不同于请求耗时补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
服务限制
服务配额及调用体积限制与请求总大小不同,实体、缓存值和批量总和都受调用边界制约;付费可增配额与系统硬限制须区分。
一个HTTP请求能接收的体积不等于一次服务调用可存取的体积。原书服务请求/响应、实体、缓存值有更小的边界,批量操作也按整个调用总量检查。切批应同时考虑数量与序列化字节,不能只因每个实体都小就断定整批可提交;具体限额须按目标版本核验。
批量总量仍受单次调用限制补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
部署限制
文件数量与单文件大小分别限制部署;ZIP/JAR减少文件数却增加解压或动态服务成本,Python处理器本身不能塞入zipimport归档。Java双集合还会重复计数,频繁部署数据应改用数据工具。
Python zipimport可从ZIP导入模块,但请求入口脚本仍须在归档外;zipserve从资源ZIP动态提供文件,走应用服务器而非静态基础设施。Java JAR也可聚合class。它们缓解文件数,不自动解决单文件体积或运行成本;冷实例解压与导入仍需资源。
归档减文件数仍有运行成本补充本节结论的独立卡片及原书依据。
本书Java文件可能同时计入资源和静态集合,故须检查两个集合及排除规则;单文件大小、文件总数和每日部署次数又各自有上限。定期传业务数据不应靠反复部署代码完成,应使用相应数据通道。书中3000文件、250次等是历史值。
部署计数与上传频率独立核算补充本节结论的独立卡片及原书依据。
有关资源使用量的头
开发者登录可在响应头观察请求资源和估算千次成本;具体图3-2已读取,单请求估算不是整体账单或普遍性能值。
原书开发者响应头X-AppEngine-Estimated-CPM-US-Dollars按当时单价表示该请求成本的一千倍,Resource-Usage分列墙钟及应用/API CPU毫秒。图3-2只是一次历史观测;负载分布、缓存命中和价格变化都会影响总量,不能拿某次请求头替代全应用成本核算。
请求估算成本不可直接外推账单补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
第4章 数据存储区实体
第4章先把实体身份和属性数据分开:完整键负责定位,kind只分类而不强制统一结构。Python Model、Expando与Java对象映射或低级API各自承担不同校验责任,空值、多值、语言类型转换和索引资格都影响往返含义。读取、整实体保存与删除可批量减少调用,但批量不自动成为事务;创建对象、完整键、曾保存状态也分别不等于当前实体存在或最新改动已落库。
实体、键和属性
实体键含应用、类别和键名或ID,创建后固定;属性可多值且同类别不必同结构。关系表类比只用于入门,键并非可改属性。
实体是数据存储中的一个对象,kind用于逻辑分类,属性保存有名字的值。同kind实体可以有不同属性,同名属性也可能存不同类型;一个属性还可多值。这种无固定模式的灵活性把契约维护责任留给应用,不能把同kind直接等同于固定列结构的关系表。
底层kind不强制同一属性集或类型;属性可多值。实体身份属于键,键名与数字ID二选一,且创建后各部分固定。应用或模型层的一致结构是另一层约束,不由kind名称自动保证。
基于属性的查询以一个kind界定候选范围,但它不保证候选具有一致属性或类型;因此模型一致性会影响查询的可解释性。
实体建模补充本节结论的独立卡片及原书依据。
实体身份与属性分开补充本节结论的独立卡片及原书依据。
Python数据存储区API简介
Python Expando容纳动态属性,Model提供结构校验但不约束所有入口。构造、首次put分开,保留属性名有API与底层两层规则;同键put会覆盖,get_or_insert提供原子占位不等于属性初始化完成。
db.Model在应用对象层检查声明的属性与类型,Expando和其他低层入口仍可写出不同结构。问题可能直到再次按Model加载才暴露。更改模型定义前要核对已有数据及全部写入入口,不能把一个类通过校验等同于数据库全体实体满足新结构。
数据模型还决定实体组和索引如何服务业务需求;底层无架构不是无需结构,而是应用负责让所有读写路径遵守可解释的规则,并安排旧数据迁移。
模型校验不是全库结构约束补充本节结论的独立卡片及原书依据。
本书get_or_insert按键返回已有或刚创建的已保存实体,避免普通同键put直接覆盖。但示例随后检查title再填其他属性,不能由此断定整段初始化已原子化;多个请求的后续修改仍需并发协议。是否新建应由明确业务结果描述,不能用某业务字段非空随意替代。
创建占位不等于完成初始化补充本节结论的独立卡片及原书依据。
Python API的key_name等名称受构造参数及方法约束,单下划线对象属性被忽略,底层另保留双下划线包围的名称。动态生成属性时同时检查API与存储层命名规则,避免把未持久化的辅助状态误认作已保存业务属性。
属性保留名要按接口核对补充本节结论的独立卡片及原书依据。
Java数据存储区API简介
JDO/JPA以对象映射访问底层服务;低级Entity API可处理动态属性结构,结构仍由应用管理。例中自动ID与显式字段标注为后续JPA章节铺垫。
标准接口不能抹平平台差异补充本节结论的独立卡片及原书依据。
属性值
表4-1两张图已逐项实读。存储类型及语言包装不总相同,低级API可能扩大类型;短字符串按UTF-8字节而非字符限制,长Text/Blob不索引。GData包装保留语义,不代表特殊查询引擎。
本书短字符串可索引且按UTF-8字节限制,长Text可容纳更长文本但不参与属性索引;中文等多字节字符的字符数不能直接当字节数。二进制也分短ByteString/ShortBlob与长Blob,不能把原始字节直接按文本编码处理。具体500字节边界仅属于书中版本。
字符串长度与索引能力分开补充本节结论的独立卡片及原书依据。
低级API会按存储原生类型归一化,例如Java Integer取回为Long,浮点值按双精度保存;模型层可把它们转回声明类型。调用方应按所选接口的返回类型处理,而不是假定保存对象的语言类型必然原样恢复。
存储往返可能改变语言类型补充本节结论的独立卡片及原书依据。
表4-1区分文本、二进制、64位整数、双精度数、日期、空值、Key和User;GData包装还包括GeoPt、Rating及通信地址类。选择类型时先辨索引需求、可序列化表示与语义范围,GeoPt是经纬度对而非自动地理搜索服务,Rating是书中1至100整数。类型表04331/04332已人工阅读,结构化来源定位仍为本节XHTML。
属性类型按用途选择包装补充本节结论的独立卡片及原书依据。
未设置与空值
设置为空与属性未设置不同;Python None、Java null都是值,删除属性则改变存在性,后续索引语义也不同。
一个实体的prop2=None仍具有prop2属性;另一个实体不设置prop2则没有该属性值。Python动态模型可del,Java低级API用removeProperty删除;设成null不等于删除。数据迁移和查询设计应分别测试缺失、空值和实际值,不能把三者合为一种状态。
空值不同于属性缺失补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
多值属性
多值属性可含不同类型并保留输入顺序,Expando空列表受限而Model可映射未设置;JavaCollection回读为List,原集合结构不会自动恢复。
本书多值属性保存元素及顺序,Python列表可含混合类型与None;Java Collection按迭代顺序写入,读回List,HashSet等原有集合语义不会自动保留。Expando不接受零值空列表而Model另有转换机制,空列表、未设置和包含null的列表须按接口区别。
Python list是多值属性的表示而不是可任意嵌套的原生值类型,列表内不能再放列表;空列表需要ListProperty等模型规则解释。
多值属性不保留全部集合语义补充本节结论的独立卡片及原书依据。
键和键对象
完整键可直接查找或保存为引用;自动ID首次put前键不完整,显式键完整也不证明实体已存在。键字符串可逆编码不保密,Java需KeyFactory而非toString。
未指定键名的新对象在首次保存前尚无数字ID,键不完整;显式键名可使键提前完整,但对应实体可能尚未保存。Key完整性检查只回答身份部分是否齐备,不回答存在性或写入是否成功;需实际读取或受保护的创建操作确认。
键完整不表示实体已经存在补充本节结论的独立卡片及原书依据。
实体键可转为便于URL或表单传递的字符串,编码可逆,类别及键名中的敏感信息也可被还原。Java须用KeyFactory.keyToString()/stringToKey()完成这一编码,Key.toString()不是等价传输格式。知道或成功解码一个键,也不代表获得相应实体的访问权限。
键的文本编码不是保密手段补充本节结论的独立卡片及原书依据。
使用实体
按完整键直接取实体可批量调用;Python缺失项为None,Java低级批量返回Key到Entity的Map。批量减少RPC仍受总量及数量限制;原文构造Key的疑似误写不复制。
Python db.get键列表可返回包含None的结果,Java低级批量接口返回Map。读取后须按各自接口核对哪些键实际存在,不能假定整批都找到或把Map当同长有序列表。批量减少往返但不取消数量、响应体积和权限检查。
批量读取要保留缺失语义补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
查看实体对象
实体对象检查区分键、类别、属性与是否曾保存;is_saved不跟踪脏数据,动态属性列表需instance_properties而非dir。
Python is_saved()只说明对象曾保存或从库加载,修改属性后仍为True。不能用它判断改动是否已持久化或是否需要写入。动态实体属性枚举也应走instance_properties等API,而非假定普通dir()就能列全存储属性。
曾保存状态不等于当前无修改补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
保存实体
put按整实体保存,同键创建与更新共用入口。先查不存在再创建有竞争窗口,需事务保护;批量保存并不由一次服务调用推导出跨实体原子性。查询立即可见的描述只限历史存储实现,后续事务章展开。
本书put发送完整实体并按键创建或替换,不能只提交一个被修改属性。两个请求分别读取旧实体、修改不同字段再保存,仍可能相互覆盖;这是由整实体替换推导的风险。先检查键不存在再创建也须事务或原子接口保护,不能仅凭先前读取结果保证唯一创建。
整实体覆盖需保护读改写补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
删除实体
删除可按对象或完整键执行,批量减少调用;不必先读取内容才能按键删除,不将批量当跨实体事务。
Python delete可接受实体或Key,Java DatastoreService.delete接受一个或多个Key。已知合法目标键时可省去为获得对象而做的读取;批量只减少服务调用,不自动提供跨实体原子性,删除前仍应确认业务范围与授权。
按键删除无需先装载实体补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
第5章 数据存储区查询
第5章从查询条件、结果形态与延迟执行进入索引原理:查询形状决定列序和方向,边界定位后扫描连续区间,纯等式还可合并单属性索引。字段缺失、存储类型和多值属性会改变匹配与顺序,MVP组合更会放大写入成本。分页宜理解接续边界而非无条件加深OFFSET;自动配置只覆盖已运行的查询,发布和清理索引都要照顾所有活动版本。
第5章 数据存储区查询
查询以预先维护的索引定位已知形状结果,把写入与存储开销换作可预期的读取;不支持任意复杂聚合。
早期GAE查询依靠预先维护的索引:根据类别、过滤操作、排序属性与顺序选择可用索引,再扫描匹配范围。查询形状必须受索引支持,不是临时任意扫描实体。这里的“表扫描”应按译注理解为索引访问;可预测访问方式不等于任何负载或结果规模下的延迟保证。
查询设计必须预先考虑筛选与排序形状;该模式把部分工作前移到写入及索引维护,不是临时扫描所有实体完成任意计算。
索引驱动查询补充本节结论的独立卡片及原书依据。
查询结果和键
返回完整实体可能带来多余传输,常用字段和大载荷可拆实体并以键关联;keys-only适合只需定位目标的流程。
书中查询返回完整实体而非任意属性投影。若经常只读小部分字段,可把常用与查询属性放小实体,大载荷放另一个实体并保存引用键,按需再取。这样减少常见路径传输,却增加额外读取及跨实体一致性责任,不能只看单次对象大小。
热字段与大载荷可分实体补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
GQL
GQL仅表达存储支持的SELECT、筛选与排序,不是完整SQL;IN和!=在客户端展开多查询。表5-1已逐项读取,字面量须与属性类型相合,关键词不敏感但kind/属性名敏感。图5-1也已读取。
GQL借用SQL外观但只支持SELECT,不具备任意OR、JOIN、更新操作或属性子集投影。条件左侧是属性名或key,右侧是合适类型的简单值。设计查询要从底层支持的筛选与索引出发,不能把一般SQL表达式直接迁入。
查询语言相似不代表能力相同补充本节结论的独立卡片及原书依据。
本书GQL与Python Query把IN拆为多个等式查询,把!=拆为小于和大于两次查询,再聚合结果。多个这类条件会组合放大查询次数;一条文本语句不等于一次低成本服务调用,需核对组合数量和合并开销。
不同属性分别有4个和3个IN值时,需组合成12条等式查询;!=也继承范围查询的历史限制。属性未设置不在相关索引中,不会因“不等于某值”自动被返回。
集合条件可能展开多次查询补充本节结论的独立卡片及原书依据。
表5-1把字符串、数字、布尔、日期时间、KEY、USER和GEOPT分别表示;文本形式相似不代表类型相同,实体键应使用KEY而非普通字符串。字符串单引号内的引号用双单引号表达;参数绑定可避免自行拼接类型语法。表图04334已人工阅读,完整形式以目标版本解析器为准。
GQL字面量要匹配存储类型补充本节结论的独立卡片及原书依据。
Python的查询API
Query对象创建只描述问题,filter添加AND条件、order按调用次序排序,链式返回自身不代表执行。
Python Query/Player.all()先形成查询描述,filter把条件按AND组合,order按调用次序规定多属性排序,方法返回自身只是方便链式构建。直到获取或迭代结果才执行;创建对象或prepare成功不能代替查询真正有索引、能返回结果的验证。
Java DatastoreService.prepare产生PreparedQuery,访问结果前仍未执行;asIterable/asIterator分批取数,asList需指定限制。查询实际执行与迭代全过程都应纳入错误及期限处理。
查询构造与实际执行分开补充本节结论的独立卡片及原书依据。
Python中的GQL
GQL按位置或名称绑定实际类型值,bind可复用查询结构。示例把可变查询放全局以省解析,但复用状态须与具体并发模型核对。
GqlQuery以:1等位置或:min_level等命名占位符接收值,减少手写字符串与特殊类型字面量的负担;bind可改值复用已解析结构。不要把参数名、查询结构与用户输入混拼。全局复用可变绑定对象须另外检查并发请求之间是否相互覆盖,不能只看到节省解析成本。
参数绑定保留值的实际类型补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
获取结果
fetch/get/count/迭代都可触发查询,结果上限与迭代的期限分开。大OFFSET仍需扫描跳过,不适合深分页;count到上限不等于精确总数。历史1000条限制注明时期。
OFFSET并不是免费移动到第N条,书中系统仍需收集并扫描前面的匹配项,偏移越深成本越高且会触及限制。可按有序属性或键保存下一批边界,使用范围条件接续;边界应配合稳定排序及并发数据变化策略。
Java FetchOptions的offset也有扫描成本,换成asIterable并不会自动消除深偏移代价。
深偏移分页仍要扫描跳过补充本节结论的独立卡片及原书依据。
count(limit)达到limit只能说明至少有这么多符合项,不能证明总数恰好等于limit。fetch和count的书中最大值是历史约束;迭代虽可分批继续,仍受请求截止时间影响,处理足够后应主动停止,不能把接口无数量上限误解为工作可无限持续。
计数上限只能回答阈值问题补充本节结论的独立卡片及原书依据。
Keys-Only查询
keys-only通过Query参数或SELECT key显式选择,Python返回Key而非模型实例;Model便捷all/gql方法在本书版本不支持这一结果形态。
Python keys_only=True或GQL SELECT key返回Key,不是模型实例;本书Model.all()/gql()便捷接口又不提供此形态。消费端应明确需要键还是实体,并按实际类型访问;查询能筛选目标不表示返回了全部属性。
Java低级接口setKeysOnly后返回没有属性的Entity,通过getKey()取键;不同于Python直接返回Key,不能根据相同keys-only名称假定两者结果类相同。
只取键时核对结果对象形态补充本节结论的独立卡片及原书依据。
Java的查询API
Java Query经prepare后到取结果时才执行,迭代分批仍有超时风险,FetchOptions控制数量和偏移。keys-only返回无属性Entity而非直接Key;唯一结果接口不当作任意截取首项,实际多结果行为需按SDK核对。
查询构造与实际执行分开补充本节结论的独立卡片及原书依据。
只取键时核对结果对象形态补充本节结论的独立卡片及原书依据。
深偏移分页仍要扫描跳过补充本节结论的独立卡片及原书依据。
索引简介
索引按筛选/排序结构共享而非为每个参数值另建,范围连续扫描与回表构成读取;写入维护索引。开发服务器仅覆盖执行过的查询,冗余删除还要顾及线上其他版本。图5-2已读。
同kind、筛选属性与排序方向相同的查询可以共享索引,name等于不同用户值不必各建一份。索引先定位首项再扫描连续匹配范围,所需返回量仍影响成本;原书“速度不受数据集大小影响”应理解为索引查找避免全表扫描,不能当作任意结果量的恒定延时保证。
等式查询先定位首个等值项,扫描到首个不等值项为止;图5-4的level=10连续三项展示这一机制。
同一属性上的上下界可以把范围缩成连续区间;互相矛盾的上下界可在计划阶段判空。图示score>500且不含两个边界。
索引形状可供不同参数复用补充本节结论的独立卡片及原书依据。
生成索引配置只反映已测路径补充本节结论的独立卡片及原书依据。
索引读取收益伴随写入维护补充本节结论的独立卡片及原书依据。
自动索引和简单查询
自动索引覆盖kind、单属性等式/范围/排序及受限键查询,kind索引按键给出确定顺序。图5-3已实读。
本书自动维护kind与单属性升降序等索引,覆盖单kind全部实体、一个属性上的等式/范围/排序以及若干键查询。存在多个条件不必然要求自定义索引,关键是属性组合和排序形状;也不能因单属性都有索引就推定任意组合都可用。
排序方向也是索引形状的一部分;本书升序与降序各有自动索引。排序属性缺失的实体不会凭空出现在该属性索引里,后续章节进一步讨论这一点。
自动索引覆盖常见单属性形状补充本节结论的独立卡片及原书依据。
大于和小于筛选条件
大于、小于及同属性区间都是一个有序索引的连续范围;无效区间可预先判空。图5-5⁄5-6已读,不把正文口语“由顶扫描”覆盖前述边界定位。
索引形状可供不同参数复用补充本节结论的独立卡片及原书依据。
针对键的查询
键的确定排序支持接续分批,示例多取一项并把未处理项当下批起点;原示例key少括号,概念不等于可运行代码。
示例每次取11个、处理前10个,把移出的第11个键作为下批起点,并用>=继续,使该项仍有机会被处理。另一种“记录已处理最后键”方案则应配合>。不可把起点来自哪一项与包含运算符混搭,否则会重读或漏项;原Python示例pop().key缺调用括号,未直接执行。
分页边界要与包含规则一致补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
类别无关查询
类别无关查询覆盖所有kind但只支持键/祖先类限制,不是任意跨类别属性检索;可用键范围分批。
本书省略模型类或FROM Kind可查询不同kind实体,但不支持基于普通属性的筛选或排序;主要利用键、祖先及有界分批。跨类别不等于关系JOIN或任意全库搜索,消费端还须接受不同实体结构。
跨类别查询仍有条件边界补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
自定义索引和复杂查询
组合排序需有对应列顺序和方向的自定义索引,配置properties次序有语义。图5-9已读。
level DESC、score DESC的查询需要先按level后按score排列的复合索引,单独两个属性索引不等价。index.yaml中properties的出现次序与direction共同决定行序,不能把它当无序字段集合。只为实际形状建索引,避免枚举所有可能组合。
复合索引列序对应排序语义补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
多个属性上的筛选条件
等式列在前、范围列随后才可保证连续区间;不等式属性须作首排序,本书旧引擎不支持多属性不等式。正文及图5-10至5-12有大小号不一致,按已实读图和明确条件分别说明。
在本书索引模型中,charclass固定为mage再限定level范围,按charclass、level排列才能形成连续片段;反过来会让其他职业插进范围。正文与图示的10存在不一致,但两者说明的是同一列序原则,不能把互相矛盾的边界当同一查询结果。
等式前缀让范围结果连续补充本节结论的独立卡片及原书依据。
本书旧查询引擎要求不等式属性先排序,再按其他属性排序;同一属性可同时有上下界,但多个属性的不等式不能由一个连续区间满足,因而该版本拒绝这种查询。此为历史引擎能力边界,不宣称当代Datastore仍完全相同。
范围筛选约束后续排序补充本节结论的独立卡片及原书依据。
多个等式筛选条件
纯等式无排序查询可通过单属性索引的候选键合并求交,无需总预建复合索引;大量拒绝候选仍可能超时,需要复合索引优化。图5-13已读。
每个等值段内部按实体键排序,查询在各索引推进候选键,只有所有条件都确认同一键才返回;因此无需先收全结果再排序。若候选大量被否决,扫描仍可能过慢而触发书中NeedIndexError,复合索引可用写入与存储成本换读取效率。它是条件交集,不是跨实体属性JOIN。
等式索引合并依靠键交集补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
未设置和不编入索引的属性
索引要求所有相关属性已设置且可索引;缺属性或Text/Blob不会命中该属性条件,连仅排序也会排除。显式None与缺失仍不同,取消索引可省维护但改变可查询性。
实体必须具有索引涉及的全部可索引属性才有相应条目。缺失、显式不索引及本书Text/Blob都会使它无法成为该属性筛选或排序查询的结果;ORDER BY也不是只改变已有结果的顺序。需要表示“未知但可查询”时应明确设计空值与默认值,并迁移旧实体。
Python声明indexed=False后,实体仍有值,但以该字段排序计数可为0;这只说明没有相应索引条目,不能说明实体不存在。
缺少索引属性会被查询排除补充本节结论的独立卡片及原书依据。
排序和值类型
不同值先按存储类型族再按族内规则排序,整数与浮点不能混作数值总序。表5-2已读,包括包装类型的底层表示与排序。
本书索引先按类型族排序,再比较同族数值,因此浮点数与整数混存时不会得到普通数轴顺序;日期等包装还按底层表示参与排序。若业务需要可比较的排名,应在模型与迁移中统一类型,不要仅依靠属性同名。
数值排序先统一存储类型补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
查询和多值属性
MVP以成员等式支持标签/战利品集合查找,也便于从实体直接列出成员;不需要为只有名字无细节的每个成员建立独立实体。
Player.trophies保存战利品名称列表,读取实体即可列出全部名称,WHERE trophies=某名则查含该成员的玩家。适用于成员本身可用简单值表达的集合;若成员有独立状态和生命周期,再考虑实体关系。一个拼接字符串不具备同样的成员索引语义。
多值等式表示成员包含补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
MVP和等式筛选条件
每值生成索引行,多个同属性等式可分别由不同成员满足;包含几个值不能证明精确全集或无重复。图5-14已读。
MVP上的prop=a AND prop=b可由同一实体的两个不同成员满足,因此并不矛盾。它只证明包含a和b,不能证明没有其他值,也不能证明各值只出现一次。若需要精确集合相等,须另外设计规范化表示或校验,不把成员筛选误作列表全等。
成员都匹配不等于集合相等补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
MVP和不等式筛选条件
范围查询可能匹配同实体多行,首个匹配行决定返回顺序并去重。图5-15已读,e2因4先于e1的5返回。
查询按索引扫描,同一实体多个成员可能都匹配,但第一次匹配决定该实体位置。prop>3升序时,含4/6/8的e2先于含1/3/5的e1,因为参与比较的是首个匹配4与5,不是整个列表或无条件最小值。
无范围过滤时升序取最小成员、降序取最大成员,拥有两端极值的同一实体可在两种方向都排首。本书还会丢弃等式条件同属性的排序,不能期待用a=3 ORDER BY a DESC按该列表其他值决定顺序。
多值排序看首个匹配成员补充本节结论的独立卡片及原书依据。
MVP和排序规则
无筛选多值排序由最小/最大成员决定,故升降序可能同实体领先;本书等式属性上的排序会被计划器忽略,不可依赖它按其他成员重新排序。图5-16已读。
多值排序看首个匹配成员补充本节结论的独立卡片及原书依据。
爆炸式索引
多个MVP同时进入复合索引会生成成员组合,索引项乘法增长而非相加,可能令实体写入失败;历史5000值限制不代替模型控制。
一个MVP参与索引产生多个条目,两个MVP共同参与则为成员值的各种组合生成条目,数量可能按乘积增长。写入要维护这些条目,实体很小也可能因索引过大失败。建模时估算组合基数、所涉索引数和更新频率,不能只检查实体正文体积;具体硬限额须按目标版本查证。
多值复合索引会组合膨胀补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
配置索引
Python index.yaml声明kind、ancestor和有序properties,自动区只增不删;–require_indexes使本地缺索引报错,测试要覆盖所有查询形状。
Python开发服务器可用–require_indexes禁止自动补配置,使缺少自定义索引的查询像线上一样失败。index.yaml的kind、ancestor及属性顺序/方向应来自实际查询形状;#AUTOGENERATED分隔自动区域,但工具不会判断旧索引能否删。测试既要覆盖成功形状,也要验证发布配置遗漏会被发现。
关闭自动补索引测试缺失路径补充本节结论的独立卡片及原书依据。
服务配置不随代码版本隔离补充本节结论的独立卡片及原书依据。
Java中的索引配置
Java手工datastore-indexes.xml与生成datastore-indexes-auto.xml共同构成配置,autoGenerate=false测试缺索引;生成器不删除,配置移交需显式维护。
本书Java在WEB-INF/datastore-indexes.xml维护手工索引,自动生成内容另放WEB-INF/appengine-generated/datastore-indexes-auto.xml,两者共同生效。autoGenerate=false可关闭自动补齐;kind、ancestor、property顺序和direction都须核对。版本控制时可移入手工文件,但不能漏掉仍需的自动配置。
Java索引配置合并补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
第6章 数据存储区事务
第6章用公告牌消息与计数说明,单实体原子性不能替代整段读改写事务;实体组把必须一起提交的数据放在同一冲突域。Python函数包装与Java显式事务采用不同调用方式,但都须重读重算并处理失败,事务外副作用不会随数据库回滚撤销。提交日志与应用实体/索引分阶段,使报错后仍可能已提交;稳定业务身份与状态检查才让重试安全。跨组批量可部分成功,独立读取和查询候选也不自动形成共同快照。原文前滚说明的前后差异保持明确,不据此扩大平台一致性承诺。
第6章 数据存储区事务
公告牌消息与计数说明两类问题:部分失败造成对象和计数不同步,并发读改写则可丢失一次递增。实体组限制为低成本原子事务划出范围,组内竞争与吞吐量需共同设计。
两个玩家都读到消息数10,各自创建一条消息并把计数写成11,正确值本应12;即使单次实体写入原子,也不能保护整个读改写。另一个失败窗口是消息创建和计数更新只成功其一。案例的对策见[[消息和计数放入同一事务]],其原子性仍不等于客户端重复提交幂等。
公告牌计数会丢失并发递增补充本节结论的独立卡片及原书依据。
把公告牌计数实体和新消息放在同一实体组,在一次事务中读取计数、创建消息并递增计数,失败则整组操作不生效;冲突后重读再计算。它解决[[公告牌计数会丢失并发递增]]中的读改写和部分成功问题;若同一业务请求可能再次提交,还需稳定请求身份及去重检查。
消息和计数放入同一事务补充本节结论的独立卡片及原书依据。
实体和实体组
实体组由根键路径决定,成员关系创建后固定;kind与组无必然关系,父/根实体记录不存在也不破坏键路径。乐观冲突检测按组发生,热点应按独立一致性需求分片。
同组不同实体的更新也可能互相冲突,组越大不一定越便于扩展。按必须原子维护的数据设计组,使独立用户或业务自然落入不同组;避免每次首页访问都更新同一个强一致实体。分片提升并发空间,也会增加跨片聚合或一致性设计责任。
实体组边界也决定冲突范围补充本节结论的独立卡片及原书依据。
同根键路径决定实体组,父或根实体可以尚未存在或已被删除,子实体仍保留原组与完整祖先路径。kind也不决定组,一个组可含不同kind。不能把parent键当作自动维护的外键约束或级联删除承诺。
祖先键关系不要求父记录存在补充本节结论的独立卡片及原书依据。
单次实体更新要么完整成功,要么失败;要让多个实体共同完成更新,本书的早期GAE模型要求先把它们组织进同一实体组。实体组界定本地事务范围,也影响并发争用:大量用户更新同一组会更易冲突。先明确哪些数据必须共同保持一致,再设计分组,不能把全部数据塞进一组换取表面的方便。
实体键的根路径决定本书事务组,创建后不可移动;乐观控制在提交时判断同组是否已有其他成功更新,而非保证所有写入都无需等待或重试。
实体组事务补充本节结论的独立卡片及原书依据。
祖先查询
祖先筛选匹配路径前缀,可跨kind取子孙但常需配置索引;不应为了层次检索把全体对象纳入大组,可将路径前缀保存为多值属性另查。
祖先查询可匹配整段祖先路径下的实体,但同根路径也把它们绑定到一个竞争组。若只需层次浏览,可把/A、/A/B等前缀存为多值属性,用成员等式查询;这样保留检索能力,却不获得祖先事务的一致性保证,两种建模目的应分开。
层次检索不必强绑事务组补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
事务中都会发生些什么
单事务限定同实体组,查询须有匹配祖先;只读事务读取共同开始快照。再次读取已写对象仍见事务起点版本,不能当read-your-writes。只读不冲突不表示没有其他故障。
本书事务内读取基于开始时版本,更新实体后再get仍可能返回更新前状态。后续计算应复用事务内已修改对象,而非误认为再次读取会看到待提交写入。只读事务可保证同组多实体快照,但仍受服务错误、范围和期限约束。
读取公告牌计数和随后查询消息是两个操作;若业务要求两者严格对应,应放在同组只读事务中,而不能只凭查询带祖先就认为两个独立操作共享快照。
事务快照未必读到自身新写补充本节结论的独立卡片及原书依据。
本书事务可按键读取、修改或删除同组实体,事务内查询也必须带能确定该组的祖先条件;混入其他组或无祖先查询会由API拒绝。无需显式声明组不代表没有组限制,实际键路径仍决定所有操作是否属于一个事务范围。
事务查询必须限定同组祖先补充本节结论的独立卡片及原书依据。
Python中的事务
Python run_in_transaction包装函数、参数、提交与冲突重试,异常取消事务,Rollback可静默取消。重试函数必须重新读状态并控制非事务副作用,耗尽后适当报告。
run_in_transaction可用相同参数多次调用事务函数,数据库回滚不撤销已经发送的邮件、HTTP请求或其他非事务动作。事务函数应围绕受保护的数据状态重算,外部效果另用提交后处理或受支持的事务排队机制;不能把函数被调用一次当成必然只执行一次。
重试事务函数不能重复外部副作用补充本节结论的独立卡片及原书依据。
Python事务函数抛普通异常会取消并重新抛出,db.Rollback用于取消而不再次抛出该异常;并发失败可按默认或自定义次数重试,耗尽后为TransactionFailedError。调用者应根据业务成功结果决定响应,不能把没有普通异常就一律当作已提交。
事务包装器区分回滚与重试耗尽补充本节结论的独立卡片及原书依据。
冲突重试要重新读取计算补充本节结论的独立卡片及原书依据。
Java中的事务 · 连续片段1
Java beginTransaction/commit/rollback明确生命周期,当前事务有栈语义,也可显式传事务或null脱离事务。示例每次重试重新获取公告牌,成功只在commit后标记;错误路径应显式清理活动事务,不直接复制示例。
Java低级API可把Transaction传给get/put/delete;传null则使该操作在事务外立即执行,即使存在当前事务。当前事务栈只影响未显式指定的调用,多个事务对象也不自动构成嵌套原子事务。审查时逐个确认数据操作的归属,避免以为整段代码都被一个commit保护。
显式事务参数决定操作归属补充本节结论的独立卡片及原书依据。
Java示例在txn.commit()成功后才置success=true,冲突则重新开始并重读,次数耗尽向用户报告失败。实际实现还应清理失败后仍活动的事务并区分可重试错误;不要把begin或put返回当作业务事务已成功提交,也不把所有异常无差别重试。
提交成功后才报告业务成功补充本节结论的独立卡片及原书依据。
Java中的事务 · 连续片段2
示例续段按公告牌键读取计数并祖先查询消息,无显式读事务;虽同祖先,分开的计数读取与查询不自动共享一个快照。
事务快照未必读到自身新写补充本节结论的独立卡片及原书依据。
实体是如何被更新的
事务分操作、提交、应用三个阶段,以实体组版本检测冲突,再把已提交日志前滚到实体及索引。提交后应用失败仍可能向调用者报错,业务重试需判重。关于事务外读取前滚的概括与随后读取节不一致,不采用该概括扩张一致性保证。图6-1⁄6-2已读。
按本书历史机制,提交阶段原子检查组版本并记录已提交更改,应用阶段再更新实体与索引。提交后应用失败不等于该业务一定没发生,后续可按已提交日志前滚。书中关于事务外读取是否前滚的表述前后有差异,本卡只使用明确的提交/应用分离,不据此宣称所有外部读都立即一致。
提交决定成功应用仍可滞后补充本节结论的独立卡片及原书依据。
若事务已提交但应用阶段报错,客户端可能只看到异常而无法判断业务是否发生。重新执行创建操作应使用稳定业务键,并在事务里检查是否已处理;仅给新实体固定键可避免重复实体,却未必避免计数再次增加。自动数字ID每次新建更可能产生重复,必须区分重试整项业务与单纯覆盖同一对象。
报错重试须考虑已提交结果补充本节结论的独立卡片及原书依据。
实体是如何被读取的
读取节强调只读事务按开始时间取版本,事务外读取可能看到不同实体的新旧混合。与上一节笼统前滚说法的冲突已明确限缩,不把独立读取拼成共同快照。
本书事务外获取可能返回不同应用进度的实体,多个读取即使各自成功,也不代表来自同一业务时点。需要跨实体一致观察时,应在受支持的同组事务内读取。此结论不依赖前节对事务外前滚的含混概括,也不泛化为当代所有Datastore模式。
多次独立读取不构成共同快照补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
批量更新
批量调用按实体组分组并行,同组事务处理,跨组可能部分成功而整体抛异常。一次RPC不等于全批原子提交,重试要核实各组状态。
本书批量更新按实体组分别执行,一个组的冲突不回滚其他组已经提交的更新,API仍可能向调用方抛异常。重试前需依据各项稳定身份与业务状态判断,不能把“整批报错”解释为“所有项都没发生”;若业务必须原子提交,应先确认它是否能落入受支持事务范围。
跨组批量失败可能已有部分成功补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
索引是如何被更新的
索引和实体应用可不同步,非祖先查询索引版本与实体版本可能不配套;祖先/事务限定组后可提供书中更强保证。精确业务判断需重验查询候选,图6-3已读;并行维护不被解读为索引数量无成本。
书中非事务跨组查询可能用旧索引选中实体,却读到已更新属性,或反过来,新旧并行使结果与原条件暂不一致。精确动作前应在适当事务或受保护流程重新校验候选;单纯拿到结果列表不能证明它们在执行动作时仍满足条件。祖先查询的历史一致性保证也不扩展到任意跨组查询。
查询候选还需满足业务时点补充本节结论的独立卡片及原书依据。
索引读取收益伴随写入维护补充本节结论的独立卡片及原书依据。
第7章 用Python进行数据建模
第7章把模型视作业务与无架构存储之间的适配层:属性声明验证、补默认并转换类型,却不会自动迁移旧实体。引用的惰性读取和反向查询让关系易用,也隐藏访问成本及悬空引用风险;一对一、多对多还需额外约束与取舍。继承复用与存储多态分开实现,PolyModel通过根kind和类型路径支持后者。扩展Property时必须保留基类契约,保证默认值、验证、双向编码和排序语义相互一致。
第7章 用Python进行数据建模
数据建模把业务对象翻译成实体、组与索引,Expando的灵活性不替代应用结构要求;Model系列提供校验,但迁移仍由应用管理。
模型校验不是全库结构约束补充本节结论的独立卡片及原书依据。
模型与属性
Model声明结构、Expando允许动态属性且也能声明静态属性;下划线辅助成员不持久化。原书本节对未设可选属性有先称缺失后称已设的差异,后续验证节明确以模型默认值处理,不据此混同底层缺失与None。
模型对象可以包含辅助成员和方法,只有API识别的属性才持久化。Model以声明约束存储结构,Expando又允许动态属性,二者均忽略单下划线开头的辅助成员。原书此前把未声明属性赋值说成错误、本节又强调忽略,具体行为须按SDK核对;不能靠普通对象赋值成功判断数据已存入实体。
模型成员与实体属性并不等价补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
属性声明
属性声明对象经描述器介入赋值,负责验证、默认值与存储类型转换;表7-1两图已读,日期/引用等包装不等于底层额外类型。
StringProperty等声明赋给模型类属性,由描述器在实例赋值时校验,并负责默认值与原生类型转换。表7-1还列Date/DateTime/Time、Reference/SelfReference和User等声明;选择声明应对照用途和索引能力,不能把类属性中的声明对象误作每个实例共享的业务值。
属性声明负责赋值与存储适配补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
属性的验证
required/default/name/choices/validator各有职责;required禁止None而默认值可填充,name映射存储字段,choices和自定义验证增加业务限制。
required禁止None,default在未提供值时填充,choices限制可选值,validator再检查业务条件。默认值也须满足验证,必要属性若有合格默认值不必显式传入;choices不含None时省略值也可能失败。不能只测试正常赋值而忽略构造时的默认路径。
声明校验需覆盖默认与显式值补充本节结论的独立卡片及原书依据。
name参数可把对象song_key映射为实体属性key,从而避开API成员名称占用。读写和查询时须辨明引用的是对象属性名还是实际存储名;重命名代码成员不等于已经迁移数据库字段。
对象名称可与存储字段映射补充本节结论的独立卡片及原书依据。
不编入索引的属性
indexed=False保留实体值但不建索引,对该属性排序/过滤不能返回此实体;示例count为0不能解释为库中无Book。
缺少索引属性会被查询排除补充本节结论的独立卡片及原书依据。
自动值
日期自动值区分首次保存与每次保存,用户自动值来自当前请求;在类定义求当前用户会被缓存实例错误复用,因此UserProperty不支持default。
在类定义中执行users.get_current_user(),结果取自模块加载时的请求,并可能随缓存实例被其他用户复用。本书UserProperty因此禁止default,应使用auto_current_user或auto_current_user_add按保存时请求取值。当前请求未登录会得到None,自动填充也不代替授权判断。
默认表达式不能捕获请求身份补充本节结论的独立卡片及原书依据。
本书auto_now每次保存覆盖为当前时间,auto_now_add只在首次保存设置;UserProperty也区分当前编辑者与首次创建者。选项表达不同业务含义,不能用更新时间冒充创建时间,也不能把实例系统时钟当作跨节点唯一事件序号。
自动时间区分创建与更新补充本节结论的独立卡片及原书依据。
列表属性
ListProperty统一元素类型并将底层缺失解释为空列表,禁止None元素;默认列表浅复制,不支持required,需要非空验证器。
ListProperty把底层没有该属性解释为对象上的空列表,并约束元素为指定原生类型,None及嵌套列表不是通用合法元素。它不支持required,若业务必须至少一个元素要自定义validator;default列表按本书浅复制,不能误认任意深层对象都独立。
列表声明定义缺失的对象语义补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
模型和架构的迁移
修改模型只改代码不改旧实体,类型变化或新增必要字段可能使加载失败;新增可选字段虽可加载,旧实体也未自动进入新属性索引。
改模型后历史记录仍保持原样,新增必填或改变类型可在加载校验时失败。新增可选字段及默认值虽能使对象加载,旧实体未写回前仍可能缺少新字段索引,无法被新查询找到。迁移计划应覆盖加载兼容、回填和索引可见性,不能只编译新类。
GAE模型不需Django syncdb创建关系表,不代表旧实体无需迁移;新增字段及索引回填责任仍在应用。Helper BaseModel主要为测试等适配,不把GAE变成原生Django关系数据库。
模型升级不会自动迁移旧实体补充本节结论的独立卡片及原书依据。
对关系进行建模
ReferenceProperty存完整键并检查目标类别,惰性解引用按当前持有对象缓存;反向属性实为查询且无需手工双写。引用不保证目标存在,删除也不级联。
ReferenceProperty保存目标键,首次访问br.book.title时才读Book,并把结果缓存于该BookReview对象;另一个评论对象仍可能再次读同一本书。便利语法可能形成逐项读取,需根据访问模式选择批量取键或减少解引用,不能把属性访问都当内存操作。
引用解引用隐藏额外读取补充本节结论的独立卡片及原书依据。
collection_name建立的反向属性在访问时执行“引用键等于本实体键”的查询,不作为字段保存在目标实体。多个同类引用需不同名称消歧;引用键只须完整,不强制指向现存实体,解引用缺失目标会失败,因此删除和悬空引用处置仍由应用负责。
反向引用是查询而非双写列表补充本节结论的独立卡片及原书依据。
一对一关系
引用可表示一对一意图但不强制唯一性;双向保存需维护两处,一对一拆大头像需显式清理关联对象。
ReferenceProperty能表示伙伴引用,却不自动保证没有第二个对象引用同一目标。若业务要求一对一,应设计唯一身份或事务约束;双向保存又要维护两端一致。把头像从Player拆成单独实体减少常见读取量,删除Player时仍须决定如何清理头像。
一对一关系仍需强制唯一补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
多对多关系
多对多可在较短一端存键列表,或为每个成员关系建链接实体以承载元数据;两端都大时链接实体更合适但增加读取。无JOIN,冗余字段同步需选择同组强一致或任务最终一致。
玩家加入少数公会、每会很多玩家时,把公会键列表放Player端,反向用成员查询,避免把长名单塞进Guild。两端都长或需记录加入时间等元数据时,可用GuildMembership关系实体。后者多一次关系读取,且不提供SQL JOIN;冗余字段还需同步策略。
多对多选短键列表或关系实体补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
模型的继承
Python继承可复用属性但普通子类存独立kind,不自动支持父类查询子类;重复声明禁止,钻石同源继承允许。
普通Model子类继承父类属性,但实例以子类名存kind,查父kind不会自然返回子kind。重复定义同名声明会报DuplicatePropertyError;钻石继承若同源声明则可复用。语言中的is-a关系和底层查询范围是两套机制,应通过实际映射设计衔接。
类继承不自动成为存储多态补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
查询和多态模型
PolyModel同继承树共用根kind,以class多值属性记录类路径,并把子类查询改为根kind加成员条件;不把全部类强塞一个树。
PolyModel把GameObject及子类都存为根kind,并以class多值属性记录继承链;查询CarryableObject时改写为根kind查询加class成员条件。因此父类查询能覆盖Bottle,并非数据库原生识别Python继承。不同业务根可分树,避免所有实体混入一个kind。
存储多态需要显式保存类型路径补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
创建你自己的属性类
自定义Property需保持基类required/choices/validator能力,validate返回最终对象值并接受合法默认;data_type描述存储核心类型。
Property子类重写validate前先调用super校验,以保留required、choices与validator,再检查自身类型和长度并返回最终值。允许None默认时自定义逻辑也须处理None;data_type指所用存储核心类型,不是任意业务对象类。绕过基类会悄悄取消公共声明参数的效果。
自定义属性先保留基类契约补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
封送值类型
存储双向转换可让业务对象映射原生字符串,并通过姓在前控制排序;分隔符必须验证或转义。文中反向钩子前称make_value_from_datastore,示例却误写for,未当可运行实现。
PlayerName编码为surname|first_name,按姓在前的字符串顺序参与索引;姓中分隔符必须禁止或转义,否则无法可靠拆回。双向转换应验证往返值、排序和非法输入,不只确认能写出字符串。原书反向钩子正文为make_value_from_datastore,示例写成make_value_for_datastore,须核对SDK,未执行该示例。
序列化格式同时决定排序与可逆性补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
自定义默认值
自定义default_value返回业务默认也须验证,非None匿名值会绕过单纯required约束,需补业务检查;示例基类default命名未验证不提供运行代码。
自定义默认值可每次构造新的PlayerName,避免共享对象;但匿名占位值虽非None,也可能不满足“必须真实姓名”的业务要求。required只按底层条件校验,需结合self.required及业务验证排除无效占位。默认值不能悄悄把缺输入变成业务成功。
业务默认值也要满足必填含义补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
接受参数
扩展构造参数须转交基类verbose_name及公共关键字,再保存require_first_name等选项用于校验;新默认值也可能因新增规则变无效。
自定义Property.init可接收require_first_name等业务选项,但须调用基类初始化并传递公共关键字,保留required等行为。验证时同时检查显式值和default生成的值;新增“名必填”会使原匿名默认不合格,应同步更新默认策略或让构造明确失败。
扩展声明参数要转交公共选项补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
第8章 Java持久化API
第8章说明Java对象层如何经DataNucleus适配GAE:配置和增强准备访问层,映射名字、主键、字段及嵌入对象决定真实存储形态。EntityManager跟踪对象,显式事务仍受实体组约束;JPQL投影与标准语法不能遮住底层调用成本。owned关系把级联和祖先组绑定,带来便利也增加竞争和迁移责任。原书若干主键字段、注解、唯一结果与前缀范围示例存在不一致,笔记已保留出处并限缩,不把简化示例作为已验证的运行代码。
第8章 Java持久化API
JPA/JDO提供模型层与可移植访问层,DataNucleus适配底层API,但平台只支持标准子集。原文规范版本号叙述不作为标准版本依据。
标准接口不能抹平平台差异补充本节结论的独立卡片及原书依据。
设置JPA
persistence.xml指定实现和持久化单元,NontransactionalRead/Write表示允许事务外访问;工厂复用、上下文按需创建和编译后增强是不同步骤。
持久化工厂与上下文分开管理补充本节结论的独立卡片及原书依据。
标注之外还需完成构建增强补充本节结论的独立卡片及原书依据。
实体和键
@Entity名字用于JPQL,kind默认来自简单类名可@Table改名;@Id字段类型决定根键或完整祖先键表示。编码字符串示例文字说String却字段写Key,已标明不复制。
@Entity(name)标识JPQL中的对象类型,默认kind来自不含包名的类名,@Table(name)可另指定kind。不同包的同名类仍可能撞到同一个默认kind,映射时须同时核对查询名、类完整路径与存储类别,而非只看Java包已区分。
持久化类名与实体类别可分开补充本节结论的独立卡片及原书依据。
String键名或自动Long ID适合本书无祖先根实体;有祖先时需Key或编码后的完整路径。@GeneratedValue与初始键状态共同决定系统ID生成。书中gae.encoded-pk示例称String却写Key,必须按实际SDK确认字段类型,不能将那段代码视为已验证配置。
主键字段必须容纳完整身份补充本节结论的独立卡片及原书依据。
实体的属性
JPA字段映射可用Basic/Transient/Lob/Column和专有unindexed控制,Id不再存普通属性;序列化Blob与集合MVP查询能力不同。
@Basic明确持久化某些非标准字段,@Transient排除辅助字段,@Id只作键而非普通属性。@Lob序列化成Blob后不能属性索引查询;集合可映为多值属性并由模型恢复声明类型。@Column与gae.unindexed再控制实际名称与索引资格,不能把“能序列化”当成“能按内部成员查询”。
字段持久化与可索引性分别声明补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
嵌入式对象
Embeddable把组件字段放进同一实体,JPQL可用对象路径访问;它不是独立关系实体,属性命名需避免碰撞并核对映射。
@Embeddable的Publisher供Book内嵌,字段与Book一起存为同一实体属性,可按映射字段查询;它不是另一个独立键指向的实体。选择内嵌还是关系,要结合独立生命周期、读取粒度及原子更新范围,不能只按代码是否分成两个类判断。
嵌入组件与关联实体不同补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
保存、获取和删除对象
EntityManager管理对象附加与变更跟踪,find缺失返回null,remove对象后内存仍存在。生命周期须关闭但关闭不替代事务显式提交;persist/merge等价仅限书中提供者,未当作通用JPA规则。
本书对象经find或persist进入EntityManager管理,关闭时会处理挂起变更;独立构造或脱离管理的对象不具备同样跟踪保证。及时释放上下文,也要按事务协议显式提交,不能把close当所有提供者通用的提交方法。原文persist/merge等价是特定实现说法,不泛化为标准JPA。
受管理对象生命周期影响写回补充本节结论的独立卡片及原书依据。
持久化工厂与上下文分开管理补充本节结论的独立卡片及原书依据。
JPA中的事务
JPA EntityTransaction显式begin/commit与活动时rollback;标准接口不识别实体组,父键扩展仍需应用保证同组。父键字段可供祖先查询引用。
EntityTransaction提供begin、commit、rollback,不会取消底层同组约束。用完整键或gae.parent-pk字段组织祖先,并在异常路径检查isActive后回滚;祖先查询还需可引用的模型父键字段。不能因JPA看似全局事务接口就跨任意实体组更新。
标准事务API仍受实体组限制补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
查询和JPQL
JPQL使用模型名称与字段,可参数绑定、限制结果并做keys-only;普通字段投影可能仍读全实体,键IN可转批取。书中single-result与LIKE等价说法已限定并纠正,跨实体DELETE无事务可能部分成功,内存补算被禁用。
本书JPQL查询普通字段子集仍先从存储取完整实体,再在接口层组装标量或Object[];只有单独@Id键投影有keys-only效果。接口返回小对象不等于网络只传小字段,性能评估应看实际底层调用而非SELECT列表长度。
投影外观不保证减少底层读取补充本节结论的独立卡片及原书依据。
书中把getSingleResult描述为有则首项、无则null,但JPA标准契约要求唯一结果,空或多结果具有异常语义。若业务只想任选首项,应明确排序及数量限制再取列表;若业务要求唯一,应保留冲突暴露。
外部核验:Oracle Query API,2026-11-14查阅,列出NoResultException与NonUniqueResultException。不声称实际测试过书中DataNucleus版本。
唯一结果查询不等于取首项补充本节结论的独立卡片及原书依据。
原书称LIKE前缀可翻为title>=前缀,但单独下界还会匹配排序在它后面的其他字符串,逻辑上不等价。前缀检索须由支持的引擎正确实施范围上界或进一步校验。不要把该简化说明复制成业务筛选条件,尤其不能以“排在后面”证明“以此前缀开头”。
前缀匹配不能只用下界代替补充本节结论的独立卡片及原书依据。
DataNucleus一般可把后端不支持的操作转成内存计算,但书中GAE禁用这一能力,避免AVG等操作先加载全类别实体。标准语法能表达并不意味着后端可高效执行;键IN转批取等特例则属于具体实现优化,需分别辨认。
访问层补算可能破坏伸缩性补充本节结论的独立卡片及原书依据。
关系 · 连续片段1
书中owned一对一/一对多以同实体组及父子路径实现级联,惰性关联须在管理器关闭前加载。mappedBy等示例有不符合标准注解的写法,概念与可运行配置分开,非所有引用都有级联。
本书GAE的owned一对一与一对多将关联对象放同实体组,按所声明cascade扩展保存、删除等操作。它方便同组原子更新,也把相关写入放入共同竞争域;直接保存Key的非所属关系不自动获得这些行为。选择关系形态需兼顾生命周期、规模和一致性,而非默认所有引用都要级联。
所属关系带来组内级联成本补充本节结论的独立卡片及原书依据。
本书JPA关联在访问时才读取目标,须在EntityManager关闭前完成所需加载;延迟到响应模板等后续阶段可能无法取到。相关字段看起来像普通属性,实际上可触发查询或读取。示例@ManyToOne(mappedBy=…)等写法不能直接作为标准注解配置,映射规则须按接口及提供者核对。
惰性关联应在上下文内加载补充本节结论的独立卡片及原书依据。
关系 · 连续片段2
已有owned对象换父需按新键重建,不能原地改祖先;级联在非显式事务下仍可部分成功。关系筛选只能查键,不能沿关系JOIN任意属性。
一个JPA操作可展开多个实体操作,若未放入显式同组事务,级联仍可能部分成功。已有owned实体也不能原地换拥有者,因为父路径是不可变键的一部分;迁移须规划重建、引用更新与旧数据清理,而非只给Java字段换个对象。
级联动作不自动构成原子事务补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
更多信息
本节仅提供DataNucleus文档及旧开源项目/测试入口,未展开新机制,登记为延伸资料而非再造知识卡。
第9章 内存缓存
第9章把缓存明确放在可丢失、可重建的次级存储位置。单键写入和计数可原子,却不能实现读改写事务或与持久层原子双写;过期、删除和回源都须考虑失败。Python与Java批量接口、命名空间、策略和错误处理的返回语义不同,合法零值也不能当失败。统计只能在明确窗口和单位下使用,原文删除保留期与年龄单位已用历史源码注明差异。
第9章 内存缓存
memcache是易失的次级存储,单键赋值原子不等于读改写或多服务事务。更新缓存失败与并发写回乱序可能遗留旧值,删除再回填和过期只是控制策略而非强一致保证。
持久层更新成功后缓存更新可能失败,并发请求还可能把旧结果后写回缓存。删除缓存、下次回源以及设过期能降低某些旧值残留,却不能原子地联动两套服务;删除也可能失败。业务若不能接受旧值,应明确校验和一致性协议,不能只在写后加一条缓存调用。
缓存失效不构成跨服务事务补充本节结论的独立卡片及原书依据。
缓存缺失必须能够重建补充本节结论的独立卡片及原书依据。
Python的Memcache API
Python memcache可用模块函数或Client;值需可pickle。set无条件、add仅缺失、replace仅存在,False可能是条件不满足或服务错误,get缺失用None判断。
set创建或覆盖,add只在键缺失时写,replace只在已有键时写;后两者返回False既可能条件不满足也可能服务失败。get返回None表示没有可用值,不能用真假值排除合法的0、False或空字符串。API结果先按其责任解释,再决定回源或重试。
缓存条件写入须区分业务条件补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
设置和获取多个值
批量缓存减少RPC但非原子,写返回失败键、读返回已找到映射;读取结果不保证同一快照。key_prefix是调用便利而非独立命名空间。
set_multi/add_multi/replace_multi返回失败键列表,空列表才表示全部写入成功;get_multi返回找到的键值映射,缺失项须单独回源。批量不是原子事务,结果也不承诺同一时点快照,不能把一次服务调用当作所有项一起成功。
批量缓存返回值描述部分结果补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
缓存过期时间
time可表达相对秒数或绝对纪元时点,写入可重置过期;不设过期仍可因资源压力驱逐,具体阈值按实际SDK核对。
time配置键的最长有效期,写入可重置计时;未设置只是没有主动到期时点,不阻止服务驱逐。相对秒数与绝对Unix时点采用不同解释,数值阈值须按实际SDK核对。TTL表达失效策略,不是保证在TTL内一定命中或与持久层强一致。
未设过期不保证缓存常驻补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
删除键
删除返回网络失败/缺失/成功三态,布尔化会合并后两种。原书将seconds说成读取锁不准确,外部历史源码明确仅阻止add、set仍可写,不当分布式锁。
Python delete返回DELETE_NETWORK_FAILURE、DELETE_ITEM_MISSING、DELETE_SUCCESSFUL;若目标是“键不存在”,后两种都满足,若要统计实际删除则不可合并。delete_multi把成功删除或原本缺失视为可接受结果,flush_all则影响整个应用缓存,不能为修一个键随意全清。
删除结果应保留需要的业务语义补充本节结论的独立卡片及原书依据。
原书把delete的seconds称为读取锁定,但Google托管历史SDK文档明确该保留期针对add操作,set仍可成功。因此它不能作为排他业务锁、禁止任何重写或强一致缓存协议的依据。
外部补充:历史memcache源码,2026-11-14读取Client.delete文档;固定提交不声称等同书中SDK1.2.5。
删除保留时间不是通用锁补充本节结论的独立卡片及原书依据。
memcache计数器
incr/decr单键原子返回新值,None才表示缺失或失败;initial_value用于缺失初始化。易失计数不能替代可靠业务账,源码还说明无符号64位边界。
incr/decr可单键原子增减,但计数可随缓存淘汰丢失,不能作唯一业务真值。返回新值可能为0,需用is None区分失败;Python initial_value可处理缺失,先get后set初始化则有竞争窗口。整数范围及溢出行为还应按实际SDK核对,原子性不消除容量边界。
本书Java increment可用负增量减少,但当时接口不支持同一次原子操作初始化缺失计数;不可用无条件put(0)初始化活跃计数而覆盖其他请求的增量。
原子缓存计数仍不是可靠总账补充本节结论的独立卡片及原书依据。
缓存统计信息
统计提供命中/缺失、项数、字节和最久未访问年龄,best effort可重置;原书年龄毫秒与历史源码秒有差异,按接口核对后才算指标。
hits/misses等是尽力统计,可能重置或溢出,比较时先确定时间窗口及基数;get_stats失败也可能无有效字典。原书把oldest_item_age写为毫秒,但固定历史SDK源码文档写秒,且指自最近访问以来的年龄,不是创建寿命。监控换算须核对实际实现,不能只照字段名猜单位。
外部核验:Client.get_stats源码文档,2026-11-14查阅;不同版本语义分别保留。
缓存统计须辨窗口重置与单位补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
Java的Memcache API · 连续片段1
Java MemcacheService配置过期和SetPolicy,批量及namespace仍需同样缺失处理;命名空间是服务对象可变状态,integer增量原子而初始化支持不同。delete第二参数本节为毫秒,不套Python秒。
MemcacheService.put可接Expiration及SetPolicy的无条件、仅缺失、仅存在三种策略,批量对应putAll/getAll/deleteAll。setNamespace修改该服务对象后续调用的命名空间,共享对象时须避免串域;Expiration相对秒、毫秒和绝对日期也要明确单位。Java示例delete第二参数是毫秒,不能把Python的秒直接照搬。
Java缓存策略与对象状态分开补充本节结论的独立卡片及原书依据。
原子缓存计数仍不是可靠总账补充本节结论的独立卡片及原书依据。
Java的Memcache API · 连续片段2
Java默认缓存错误处理可将服务错误表现为缺失或写入False;StrictErrorHandler使临时服务错误抛异常,条件不满足仍应另辨。
本书Java默认LogAndContinueErrorHandler使临时故障常表现为缺失或保存失败,并以低日志级别记录;StrictErrorHandler可改为抛MemcacheServiceException。选策略时明确是否允许回源、如何保护后端和观测异常;不能把“当前键不存在”当成已排除服务故障,也不把False一律当条件冲突。
缓存缺失可能掩盖服务故障补充本节结论的独立卡片及原书依据。
第10章 获取URL和Web资源
第10章把外部HTTP通信交给URL Fetch服务,标准库适配只保留部分接口体验,不消除协议、连接及默认值限制。同步与异步的区别在于能否重叠等待,RPC就绪、校验及成功分别是不同事实;回调又可能在等待其他请求时执行。正文完整性、重定向、证书验证和实际出口环境都需要明确,不能因拿到输入流或返回对象就认定集成已正确完成。
第10章 获取URL和Web资源
URL Fetch以服务替代任意连接,标准库被适配但仍受协议/方法/端口/请求头限制。历史HTTPS不验证证书,不能仅凭加密防中间人;限制当前URL也不防完整调用环。
urllib/URLConnection在本书GAE被改为通过URL Fetch服务发送请求,调用外观类似标准库但不等于直接套接字。协议、方法、端口、头字段和连接持久性仍受服务约束。平台只阻止直接抓取当前处理URL,应用跨其他URL仍可能形成递归请求环。
服务适配不保留全部套接字能力补充本节结论的独立卡片及原书依据。
加密传输还需验证对端补充本节结论的独立卡片及原书依据。
在Python中获取URL
Python标准库可能不能捕获全部服务异常,直接API可控制截断、重定向和deadline;标准库与API默认不同,开发服务器出口也与线上不同。
本书urllib2适配可能自动重定向并截断过大响应而不报告,urlfetch.fetch可用allow_truncated=False、follow_redirects=False及deadline明确约束。应同时处理标准库与服务异常,解析前检查状态、正文完整性及预期内容,不把成功返回对象当作完整业务响应。历史大小/时间上限不当当前承诺。
网络适配默认值要显式核对补充本节结论的独立卡片及原书依据。
开发服务器从本机发起连接,线上URL Fetch由平台代理发起;远端可能按来源地址、网络可达性或请求行为给出不同响应。验证外部集成要在实际目标出口与权限条件下进行,不能只凭本机获取成功判断线上可用。
本地出口测试不代表代理出口补充本节结论的独立卡片及原书依据。
在Java中获取URL
Java URLConnection输入流读取的是已缓冲响应,不支持持续套接字连接;直接FetchOptions控制截断/重定向,连接与读取超时在此适配中合并选择,不泛化到一般Java网络。
本书Java URL.openStream返回可读取字节流,但底层URL Fetch已把整个响应缓冲到内存。逐行读取只是消费内存内容,不意味着边下载边处理或维持长连接;超时适配规则也不能照搬到普通JRE连接。需要流式或长连接时须验证实际底层能力。
输入流接口不保证网络流式传输补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
Python中的异步请求
异步调用只把等待与其他工作重叠,每次RPC代表一个请求;get_result会等待并校验,ready可能是错误。图10-1⁄10-2已读,开发模拟同步不能直接验证并行收益。
一个RPC依次经历created、in progress、ready、checked;ready只说明获取结束,可能带错误。wait等待完成,check_result报告状态,get_result合并等待与验证再给结果。一个RPC只代表一个调用,不能复用它指代多个URL。
异步就绪与结果成功分开补充本节结论的独立卡片及原书依据。
异步外取仍受请求寿命约束补充本节结论的独立卡片及原书依据。
通过回调函数处理结果
回调可用绑定方法或闭包保存RPC,工厂函数固定每个闭包作用域以避晚绑定;等待其他RPC也可能触发当前已就绪回调,不能假定局部调用顺序。示例self.rpc/get_results复数误写未复制运行。
无参回调仍需访问自己的RPC,可由对象成员加绑定方法,或工厂函数为每次调用创建独立作用域。直接闭包引用后续会改变的外层rpc变量,执行时可能读到另一次调用对象;要固定每次捕获关系,再在回调内取结果并处理异常。
回调闭包应绑定本次调用对象补充本节结论的独立卡片及原书依据。
多个异步外取并行时,等待一个RPC也可能触发另一个已就绪RPC的回调,直到被等待者完成才返回。回调只执行一次,主例程不应假定只有调用它自己的wait才会触发处理;组件共享状态和输出次序须按这一协作调度方式设计。
等待入口不决定回调执行顺序补充本节结论的独立卡片及原书依据。
第11章 收发电子邮件和即时消息
第11章把邮件和聊天统一为服务发送、HTTP事件接收两条通路。启用入站服务、路由、消息解析、业务授权及显式回复各有职责;出站调用被接受不代表送达。多部件正文、附件、Bcc可见性和XML转义影响正确性与安全,开发模拟也不具备真实身份、递送或在线保证。聊天命令框架只完成分派,不替业务验证权限;书中的域名及服务能力均保持历史范围。
第11章 收发电子邮件和即时消息
Mail/XMPP出站走服务,入站转HTTP webhook,响应正文不会自动成为回复。历史地址域名与客户端生态不当现行服务支持清单;图11-1已读。
入站邮件或聊天由平台服务转成HTTP请求交给应用,处理器的HTTP响应用于回调交互,不会直接作为邮件或聊天正文回复给用户。若要回复,需调用对应发送API并处理其结果。应用本身也不是用户直接连接的XMPP服务器,客户端仍依赖聊天服务。
Java通过XMPPService.parseMessage(req)得到Message,再读取from/type/recipient/body/stanza;构造HTTP响应不等于发送XMPP业务回复,仍需发送接口。
消息回调响应不同于业务回复补充本节结论的独立卡片及原书依据。
启用入站服务
入站服务默认禁用,配置启用与URL处理器映射都必需,部署后通过实际控制台核对;没启用时服务不会尝试回调。
Python inbound_services或Java inbound-services声明接收mail/xmpp_message,URL映射再决定由谁处理。只有处理器而没启用服务,或启用但缺处理器,都不构成可用入站通路。按目标环境核对启用状态、URL和实际请求日志,不能仅因代码已有回调函数就判断已接入。
入站XMPP还须映射/_ah/xmpp/message/chat/,POST字段含from、to、body、stanza。原文特定版本地址一处误用appspotmail,不按该误写生成实际配置。
启用事件源与配置处理路由分开补充本节结论的独立卡片及原书依据。
发送电子邮件消息
Mail调用入队即返回,不证明送达;失败可经退信异步出现。发件人须满足历史身份约束,回复地址与退信机制分开;本地默认只记日志,SMTP/Sendmail配置可改变副作用。
Mail调用返回只说明请求交给发送服务,远端连接或地址问题可能稍后经退信出现,不能直接向业务报告收件人已读或必定送达。若以应用入站地址接收退信,须识别不同远端格式并关联原发送记录;发送API异常与最终递送结果分别追踪。
邮件入队成功不同于送达补充本节结论的独立卡片及原书依据。
本书只允许管理员、当前已登录用户或合法应用入站地址作发件人。把专门邮箱加入开发人员会赋予管理应用的能力,不能仅为发送邮件而忽视该权限。可用带会话ID的入站地址关联回复;Reply-to是用户回复指向,不将原文关于退信同样必走它的说法当通用邮件协议保证。
发件身份与开发权限不能混用补充本节结论的独立卡片及原书依据。
开发服务器默认只记录消息,Python若另启Sendmail或SMTP才可能产生真实邮件;Java示例默认日志模拟。发件人规则在本地又未完整检查,因此本地打印成功不能验收线上递送。配置测试环境前明确真实发送开关,命令与认证信息不写入共享日志;原文正文日志参数命名不一致须核对SDK。
本地邮件日志不证明真实发送补充本节结论的独立卡片及原书依据。
收件人
To/Cc可见而Bcc隐藏其他接收者地址,适合不公开名单的通知;收件人数仍消耗配额。原文把头称正文不沿用,也不承诺Bcc永远不可能收到回复。
To和Cc地址通常对收件人可见,Bcc使对应地址不列在所投递消息的可见收件人头中。群发通知可避免公开整份名单,但仍须管理逐收件人结果与数量额度;隐藏地址不等于内容保密,也不保证用户不能转发或另行回复。
收件人类型影响名单可见性补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
附件
两张附件类型表已实读,限制是历史出站允许类型与后缀。非支持载荷可发受保护下载链接,链接ID需配合权限和期限而非仅不可猜。
本书出站附件只允许若干文档、图像及文本格式,文件后缀须与类型对应;这不代表入站同样被检查。不能附加的内容可改发下载链接,并按应用需要设置身份授权、有效期与目标绑定。唯一ID便于关联但本身不等于完整访问控制。
附件限制可转为受控下载补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
在Python中发送电子邮件
Python send_mail或EmailMessage按字段准备、校验、发送;表11-2已读,文本正文与HTML/附件各自配置,地址格式有效不等于可递送或授权。管理员快捷发送有不同大小限制。
Python send_mail接收字段参数,EmailMessage可先组装再send;sender、to、subject、body为本书必要字段,html及附件可选。地址语法检查及消息初始化检查只验证结构,不验证收件箱存在、用户许可或最终递送。管理员群发快捷接口还有独立大小边界,不能按普通邮件限额推断。
邮件字段校验与发送结果分开补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
在Java中发送电子邮件
JavaMail在GAE通过平台服务而非自行SMTP连接;MimeMultipart将文本、HTML、附件组装,setContent会替换前面setText结果。原例添加未声明htmlPart明显误写,未运行。
JavaMail用MimeMessage和Transport.send交给平台,MimeMultipart装多个MimeBodyPart。设置multipart为整条内容会替换之前setText的正文,因此需在multipart内显式加入text/plain,同时配置HTML及附件类型/文件名。原例在声明htmlPart前加入它且未正确加入textPart,不作为可运行模板。
多部件邮件应显式保留文本体补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
接收电子邮件消息
入站邮件POST到含编码收件地址的/_ah/mail路径,完整MIME可有多个正文与任意附件;不能无条件取第一个纯文本体,附件名不可信且未扫描。
本书InboundEmailMessage解析POST中的完整MIME,bodies可按text/plain或text/html迭代;可能没有所期待的正文部件,不能无条件list(…)[0]。URL携带编码后的收件地址,可路由不同入口;本地控制台提交只模拟HTTP,不等于真实邮件收发通路已验证。
Java MimeMessage可从请求InputStream解析,getContent既可能String也可能Multipart,需按类型逐部件读取,并处理MessagingException;不能把所有输入都强转为纯文本。
入站邮件按多部件而非单正文解析补充本节结论的独立卡片及原书依据。
入站邮件可包含任意类型附件,文件名未必反映真实格式,也没有平台病毒扫描保证。读取或对外提供前应按内容、大小和业务用途验证并隔离处理;出站允许类型表不能作为入站已过滤的依据。
入站附件名称不能证明内容安全补充本节结论的独立卡片及原书依据。
在Java中接收电子邮件
Java在Servlet读取请求流交给MimeMessage,getContent需区分String和Multipart并迭代部件,处理解析异常;复用前述多部件边界。
入站邮件按多部件而非单正文解析补充本节结论的独立卡片及原书依据。
发送XMPP消息
JID区分用户域与可选resource,发送需按历史服务订阅关系与发送地址规则;版本地址和本地模拟不能当当前XMPP通用规则。
JID通常由用户、域和可选/resource组成,资源可标识一个客户端会话;能构造JID不表示对方允许应用发消息。本书多数服务要求先建立邀请关系,且开发服务器只记日志不连接XMPP。发送前管理用户许可、所用发送身份和版本入口,具体路由与服务支持按目标时期核验。
聊天标识与会话订阅分开管理补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
发送聊天消息
聊天发送按每个接收者返回状态,构造器与发送动作分开;默认转义XML,raw_xml/asXml仅对可信结构启用,不把NO_ERROR当最终阅读确认。
Python单JID返回单状态、多JID返回状态列表,Java SendResponse按接收者JID给状态映射;一个接收者成功不代表整组成功或用户已读。MessageBuilder只负责组装不可变消息,不完成发送。原文把状态映射一处称发送者是误写,按调用中的接收者集合解释。
聊天批发结果需逐接收者判断补充本节结论的独立卡片及原书依据。
消息默认把正文当文本并转义XML专有字符;raw_xml=True或asXml启用结构化XML节后,应确保内容是预期且合法的结构,不能把任意用户字符串未经处理嵌入协议。文本展示与结构化协议载荷要明确区分。
原始XML发送绕过默认转义补充本节结论的独立卡片及原书依据。
检查GTalk用户的状态
get_presence是历史GTalk专有能力,不是通用XMPP在线真值;需要关系,离开不等于离线,本地全部在线更不能测试真实可达。
本书get_presence只针对GTalk且依赖既有聊天关系,离开状态与连接状态不同,开发服务器则把所有地址都当在线。探测结果是某时点服务观察,不保证下一次发送成功或用户能立即阅读;发送仍须独立处理结果。
在线探测不是递送保证补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
接收XMPP消息
入站XMPP转固定POST并解析from/to/body/stanza,CommandHandler按命令名分派,普通文本与未知命令分开;原版本地址误写mail域、异常自动回复可能暴露细节均已限定。
CommandHandler把/commandname argument映射到commandname_command,未知命令走unhandled_command,普通文本走text_message。它只完成语法路由,业务方法仍应验证发送者可访问的数据与动作;BaseHandler的默认异常回复也应避免向用户暴露内部细节。
聊天指令分派不代替权限检查补充本节结论的独立卡片及原书依据。
启用事件源与配置处理路由分开补充本节结论的独立卡片及原书依据。
在Java中接收XMPP消息
Java XMPPService.parseMessage将Servlet请求转换为Message,字段访问包含来源、类型、接收JID、正文与原始XML。与Python相同通路,但具体对象API不同。
消息回调响应不同于业务回复补充本节结论的独立卡片及原书依据。
第12章 大批量数据操作和远程访问
第12章把长批处理放到本地工具,通过受保护远程API调用线上服务。原样dump/restore保留身份但绕过模型,CSV则需显式设计列转换、键与往返语义;二者的恢复承诺不同。dry-run只证明本地转换与验证,正式执行仍需对账;可恢复进度必须匹配输入和目标,限速也要分并发、记录、字节与请求资源。本地运行与管理员身份都不降低线上修改的实际影响。
第12章 大批量数据操作和远程访问
远程API把本地工具的服务调用转为线上HTTP,管理员权限与接口保护必需;可用于长批处理、转存和迁移,Python工具也能访问Java服务端。图12-1已读。
远程API把本地Python服务调用封送到应用处理器,再操作线上数据、缓存、邮件等。脚本不在沙盒且可运行较久,但每次远程调用仍消耗线上请求、带宽与服务资源。确认目标应用、版本、域和权限后再操作,不能因命令在本机执行就当成模拟环境。
remote_api_shell可选择应用及服务域,导入模型后查询,也可能发邮件或改数据;连接非默认代码版本仍共享后台状态,不能把dev域名当测试数据隔离。
本地管理脚本仍会改变线上服务补充本节结论的独立卡片及原书依据。
在Python中设置远程API
Python远程处理器须限制admin,浏览器无协议头错误可验证路由已到达但不证明完整远程协议和权限矩阵通过。
Python remote_api处理器应配login:admin,Java对应Servlet安全约束。浏览器登录后出现缺必要协议头可证明请求到了某处理器,却不能证明工具认证、读写权限与实际服务调用都通过。验收应分别覆盖未授权拒绝、管理员访问和协议调用,不能把一个错误提示当作完整成功。
Java需web.xml同时声明RemoteApiServlet、/remote_api映射及相同URL的admin约束;客户端显式传入实际路径,避免保护一条路径却把另一条暴露出去。
管理入口先限制权限再验证协议补充本节结论的独立卡片及原书依据。
在Java中设置远程API
Java映射RemoteApiServlet并单独绑定admin约束,路径传给客户端保持一致;不是仅声明Servlet就已保护。
管理入口先限制权限再验证协议补充本节结论的独立卡片及原书依据。
使用Bulk Loader工具
Bulk Loader依赖Python SDK与sqlite3模块记录恢复进度,命令位置与模块是否存在分开检查;禁用进度文件会失去相应恢复能力。
本书Bulk Loader用sqlite3模块和进度数据文件记录处理位置,相同任务可续跑;–db_filename=skip则禁用这一记录。可执行工具、Python模块、目标URL和应用ID各自核验,不能把命令能启动视为进度可恢复。恢复时还应确认输入版本、转换规则和目标未变,避免旧检查点套到新任务。
可恢复批处理依赖保存执行进度补充本节结论的独立卡片及原书依据。
备份与恢复
dump/restore按原始实体绕过模型验证,保留键与引用,同键覆盖;跨应用/开发环境转存仍需按范围验证,不是完整全库一致快照保证。
本书dump/restore直接转存实体,不使用当前模型验证,保留实体键和相关引用;恢复遇到同键会替换现有实体。下载单kind也不等于已备份它引用的所有其他kind,更不自动获得全库共同快照。恢复前核对范围、模型兼容、引用完整性和覆盖策略,成功上传不单独证明恢复正确。
原样恢复会绕过模型并覆盖同键补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
上传数据 · 连续片段1
Loader按CSV列顺序转换并用模型构造实体,generate_key控制身份、handle_entity后处理、generate_records读其他格式;Java导入也需对应Python模型,不把Expando当验证等价物。
Loader以有序列映射把CSV字符串转存储类型,再由模型校验;bool(“FALSE”)仍为True等语言转换不能代替业务解析,日期也需明确格式。generate_key提供稳定键与祖先,省略则可能每次生成新ID,同键则覆盖。列转换、实体身份和幂等策略应在导入前一并确定。
导入转换必须明确类型和身份补充本节结论的独立卡片及原书依据。
本书Loader构造器声明列与转换,generate_key决定键,handle_entity可增删属性或产出多个实体,generate_records负责把外部格式变成字符串列记录,initialize/finalize处理任务前后动作。转换函数只见单列,跨列组合应在记录生成阶段完成,不让一个局部转换隐式依赖其他行。
加载器扩展点按处理阶段分工补充本节结论的独立卡片及原书依据。
Java应用借Python Bulk Loader导入时,可重建对应Python模型,也可用Expando放行任意属性;后者只是绕过校验,不保证符合Java对象映射。应核对字段名、原生类型、键路径、默认值与索引约定,不能因远程协议相同就认定两套模型一致。
跨语言导入不能省掉模型校验补充本节结论的独立卡片及原书依据。
上传数据 · 连续片段2
导入指定配置/类别/文件,首行可跳;dry_run只做本地构造验证不接触应用,不能证明远端可写或权限可用。错误续传须保持检查点与输入一致。
本书–dry_run读取文件、转换并校验实体,不上传也不访问应用。因此它能发现格式和模型错误,却不能证明远端身份、索引、配额及写入结果正确。正式执行后仍需按键、内容与数量对账;有标题行用–has_header,不能让列名误作数据。
导入预演只验证其实际覆盖范围补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
下载数据
Exporter将实体属性按列输出,缺值默认为None会中止;默认不导出实体键,CSV往返需另定身份与编码。文字将配置文件参数写filename与末尾命令config_file不一致,未抄错。
本书Exporter默认只输出声明属性,不包含实体自身键;随后按自动ID重新导入可能新建重复实体。要更新原对象需设计键列/输出扩展及对应generate_key,并对引用编码、空值、日期布尔和字符集作对称转换。备份dump与可编辑CSV具有不同语义,不能混用。
CSV往返要额外保留实体身份补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
控制Bulk Loader
线程、单批实体数、带宽、记录速率和HTTP速率各约束不同资源;进度、日志、结果数据库文件也分工。平均限流允许突发,不当作瞬时硬上限。
num_threads控制并发,batch_size控制单调用实体数,bandwidth_limit、rps_limit、http_limit分别限制字节、记录和请求速率。小实体提高批量不代表CPU或线上错误率可承受;平均速率又可能有突发。保留进度、日志和下载结果文件的身份,按目标实际负载逐步调整。
批处理限速应同时看多种资源补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
使用远程外壳工具
远程外壳选择应用、路径和域后可执行受支持服务,模型加载路径仍需设定;读查询与发邮件等写副作用同在一个会话,本轮未执行。
本地管理脚本仍会改变线上服务补充本节结论的独立卡片及原书依据。
通过脚本使用远程API
ConfigureRemoteApi设置目标和认证函数,MaybeInvokeAuthentication可提前检查;本地长任务自由不解除每次线上调用限制。示例APP-ID非法标识及~路径未展开,未作为可运行脚本。
ConfigureRemoteApi选择应用、处理路径、认证回调及可选域,MaybeInvokeAuthentication可提前触发认证;省略时错误可能延迟到首个服务调用。脚本本地不受请求总时限,但每次封送的线上请求仍受对应服务约束。原例变量APP-ID等存在排版/语法错误,本轮未执行。
远程初始化与首次调用错误分开补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
第13章 任务队列和计划任务
第13章把长工作拆为有界任务,通过令牌桶控制启动速率和突发;这不保证顺序或最大并发。名字与墓碑只去重入队,至少一次投递仍要求执行幂等;错误终止也必须与业务完成分开。事务入队绑定本地提交和后续工作,跨组只是最终一致,金币转账案例特别需要持久去重、状态与对账,不能依赖易失锁。cron另按计划触发,需验证权限、时区和重复/漏执行,并可借队列处理重试。
第13章 任务队列和计划任务
任务与cron通过URL调用处理器,仍受请求资源限制;前者可重试、后者书中不重试,可由cron再入队。图13-1已读,实验状态与限额均按历史记录。
任务队列让用户请求先交出可延后处理的工作,再由平台调用HTTP任务处理器执行。失败可能重试,因此排队不等于业务副作用只发生一次;处理逻辑要能面对重复尝试。任务处理器仍受请求式执行限制。队列速率控制处理负载,不能单独证明任务已完成或结果正确。
请求之外的任务仍以受限处理器执行。原书未提供长驻后台进程或持久在线连接,因此把工作放入队列不等于可以无限期运行;大工作要按适合的批次和状态推进。
后台任务仍是受沙盒与期限约束的HTTP处理,可拆为多个串并行小任务;计划任务可定时入队以借用重试机制,不能把用户已收到响应当作后台已完成。
任务队列补充本节结论的独立卡片及原书依据。
任务队列
队列用令牌桶控制调度速率和突发,任务可并行而无严格顺序,资源争用可能让高并发更慢。先缓存后异步落库示例不适用于可靠主状态。
令牌按配置速率补充且不超过桶容量,启动任务消耗一个令牌,不等待前一任务完成;积累令牌允许突发。执行还受平台资源调度影响,任务顺序不严格。若任务共享热点组,提高速率和桶容量可能增加竞争与冷启动,不能直接等同更快完成整批。
令牌桶限制启动速率非并发数补充本节结论的独立卡片及原书依据。
原书举先写memcache、再入队落库来缩短响应的例子,但第9章明确缓存可丢失。若任务只持有键而未可靠保存数据,执行前缓存淘汰就可能丢失更新;这是跨章推论。可靠业务应先明确持久的任务载荷或提交状态,不能把缓存命中期待当持久化保证。
易失缓存不能托管待持久化真值补充本节结论的独立卡片及原书依据。
任务的要素
任务定义包含HTTP目标、载荷、可选延迟与名字;ETA是不得早于的时间而非准点承诺,墓碑按历史窗口去重入队,不保证业务仅执行一次。
指定稳定任务名及墓碑可在服务保留窗口内避免同名重复入队,不能阻止已入队任务因重试而重复执行。延迟或ETA也只限制最早可调度时刻,令牌和资源可能让它晚执行。业务去重必须覆盖执行阶段与超过保留窗口后的重复请求,书中七日是历史值。
任务命名去重不等于只执行一次补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
任务处理器和重试
处理器按状态码报告完成,失败指数延迟重试,成功后也可能重复执行。请求头有任务名/队列/重试数,响应正文忽略;入队版本与执行版本的历史关系影响发布兼容。
队列可能在处理器已成功后再次调用同一任务,所以重试不能再次产生同一业务效果。按稳定任务或业务ID在持久事务中检查并记录已处理状态,再决定动作;发送邮件等外部效果还须另行保证。200是队列完成信号,不应在必要业务尚未完成时随意返回。
至少一次执行要求业务幂等补充本节结论的独立卡片及原书依据。
本书默认版本入队的任务执行时随默认版本走,非默认版本入队则指向特定版本。因此发布新默认版本后可能接到旧载荷,任务处理器和数据格式需兼容或显式迁移。队列名、任务名和重试次数可用于日志关联,但请求头存在不单独证明可信来源。
任务载荷须兼容实际执行版本补充本节结论的独立卡片及原书依据。
对任务进行测试和管理
开发队列需手工Run,日志状态码判断结果;历史线上缺管理功能可改处理代码,但停止重试不代表任务业务已完成,应保留失败处置。
达到重试阈值后直接回200会让队列认为完成,即使业务实际失败。若为止住永久错误而终止,应持久记录失败、原因和后续补偿或人工处理入口,不能把“离开队列”当业务成功。开发控制台手工运行与线上调度不同,还需观察状态、日志和实际业务状态。
deferred.PermanentTaskFailure会记录错误并向队列回成功以终止重试,其他异常通常触发重试;应把这一“永久失败已处置”与业务实际完成分别统计。
停止重试必须保留失败处置补充本节结论的独立卡片及原书依据。
在Python中使用任务队列 · 连续片段1
Python Queue/Task配置目标、参数/载荷、延迟与名字,queue.yaml全应用生效且可单独更新;deferred用通用处理器而非同名队列。旧labs路径保持历史。
Python Queue指定投递队列,Task指定URL、方法、params或payload等请求内容;queue.yaml的rate与bucket_size控制队列调度。deferred默认URL虽叫/_ah/queue/deferred,默认仍进入default队列,URL名称不决定队列身份。配置作用于全应用,可用update_queues单独更新。
队列配置与处理器URL分开补充本节结论的独立卡片及原书依据。
在Python中使用任务队列 · 连续片段2
defer序列化可调用对象身份及参数,不保存调用现场;模块顶层可访问对象与独立模块是必要边界。PermanentTaskFailure记录后向队列成功只停止重试,不代表业务成功。
defer按pickle保存可调用对象及参数,任务执行时须能按模块名重新定位,不能依赖lambda、内嵌函数或当前局部环境。原书还要求把延期函数放在处理器脚本外的模块,避免main包名无法恢复;依赖的导入路径和初始化应由任务模块自己准备。
延迟调用不保存当前作用域补充本节结论的独立卡片及原书依据。
停止重试必须保留失败处置补充本节结论的独立卡片及原书依据。
在Java中使用任务队列
Java QueueFactory和TaskOptions分工,参数与payload互斥、延迟以毫秒;queue.xml全应用生效。默认URL本节与前面描述不同,不写自动默认可运行范本,建议显式指定并核验。
TaskOptions指定url、param或payload、method、headers、name及延迟;本书参数与请求体不能同时设置,countdownMillis/etaMillis按毫秒。QueueFactory选择队列,queue.xml定义速率与桶容量。原文默认URL写法前后不同,配置时宜显式指定URL并核对处理器及admin约束,不依赖该处默认推断。
Java任务单位与目标补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
事务型的任务入队操作
事务入队作为当时尚未发布的设计讨论:扣款和发后续任务一起提交,跨组动作以后发生,不能当全局强事务。金币1000案例已分问题与方案,明确原书依赖memcache锁不足,给出基于持久去重的补充推导而非冒称原文实现。
原书让Alicandria向TheBarbarousBobmcgrath转1000金币:扣减A库存与给B入账的任务一起提交,B稍后处理。若任务入账后响应丢失并重试,可能再次增加1000;任务名只防重复入队,易失memcache锁也不能提供长期去重。该案例要求区分待入账、已入账与失败,补充对策见[[持久去重保护异步入账]]。
金币转账重试可能重复入账补充本节结论的独立卡片及原书依据。
原书方案把A扣减与B入账任务放在同一事务,以跨组最终一致方式完成1000金币转账,但仅提任务名和memcache锁防重复,未给实现。结合书中缓存可丢失、任务至少一次及同组事务约束,可推导加强方案:用稳定转账ID,在B所属事务内原子检查持久去重记录、增加B余额并记录已入账;重复任务仅返回已完成结果。A侧也需转账ID防重复扣减,并保留待处理状态用于对账与修复。该加强方案为本轮明确推导,不宣称原文已实现或现实资金系统已验证;对应问题见[[金币转账重试可能重复入账]]。
持久去重保护异步入账补充本节结论的独立卡片及原书依据。
事务排队连接提交与后续处理补充本节结论的独立卡片及原书依据。
计划任务
cron按GET URL和英文周期触发,可配时区,DST会跳过或重复,本地需手工测试;cron头本身非可信授权,配置及下几次运行时间都要验证。
cron.yaml/cron.xml定义URL、schedule、description及timezone,本书省略时区为UTC;有夏令时的本地钟点可能跳过或执行两次。用cron_info查看接下来真实日期时间,再与业务日界、月周规则核对,不能只凭英文计划看起来顺口就发布。
定时计划应核对时区与未来时点补充本节结论的独立卡片及原书依据。
X-AppEngine-Cron:true区分调度来源线索,但原书明确它本身不足以阻止恶意请求;应按平台机制和配置限制URL访问。cron默认GET触发、响应和重试能力与队列不同,重要工作可由cron入队,并依靠持久业务身份应对漏触发或重复触发。
调度标识头不能代替端点授权补充本节结论的独立卡片及原书依据。
第14章 Web应用程序框架:Django
第14章以Django说明框架与平台的适配:项目骨架、版本选择、设置与WSGI入口连接请求,URL/视图/模板再组织业务。GAE模型不能直接冒充关系ORM,Helper提供管理、测试夹具和表单等适配但仍有边界。模板迭代可触发查询,管理shell与远程console作用域不同;测试断言、夹具排序、表单错误与权限也必须逐一验证,不能由“框架页面能打开”推断整个应用正确。
第14章 Web应用程序框架:Django
框架提供组织与公共组件,GAE提供其下基础设施,不同层职责分开;兼容要看数据、沙盒与依赖,不是框架能启动就全功能可用。
Web框架协调URL、视图、模板、模型和公共策略,GAE提供执行、存储与可伸缩服务。框架接入平台仍要适配数据层、沙盒和依赖;普通Django ORM或admin依赖关系数据库,不能因页面可呈现就认为已兼容所有功能。
框架组织应用平台提供运行设施补充本节结论的独立卡片及原书依据。
安装Django
Django本地安装版、平台默认版与显式选择版分开;书中0.96⁄1.1与安装命令只属历史,不执行sudo。删sys.modules条目也不等价删搜索路径。
本书平台默认Django0.96而可显式选择1.1,本地需另外安装对应版本;use_library应在导入框架前调用。自带框架、项目副本和模块缓存共同影响实际加载版本,删除sys.modules缓存并不等于从sys.path移除路径。检查真实导入位置及版本,不能只看安装包名称。
Helper会优先找项目自带Django,否则按本地或平台可用版本选择;需在main.py与manage.py一致指定并核对,不让开发与线上静默选到不同版本。
框架版本选择要早于首次导入补充本节结论的独立卡片及原书依据。
创建一个Django项目
startproject生成项目骨架不自动接入GAE;manage/settings/urls各有职责,普通开发服务器与平台模拟器不同。
本书django-admin.py startproject创建包、manage.py、settings.py和urls.py;普通Django runserver并不知道GAE服务。仍需适配入口脚本和app.yaml,或使用匹配版本的Helper。骨架创建成功只证明初始文件存在,不代表存储、身份和沙盒测试环境已建立。
项目骨架生成不完成平台接入补充本节结论的独立卡片及原书依据。
请求处理器脚本
脚本先选Django版本、设DJANGO_SETTINGS_MODULE,再创建WSGIHandler;前端静态分流与框架动态路由并存,ROOT_URLCONF需匹配实际包布局。
本书入口先use_library选择版本,再设DJANGO_SETTINGS_MODULE,之后导入Django并经WSGI适配运行。app.yaml仍负责静态分流和动态脚本入口,ROOT_URLCONF须对应项目作为应用根目录后的实际模块路径。显示It worked只验证基本接通,不证明所有业务依赖已适配。
框架入口依赖初始化顺序补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
Django App Engine Helper
Helper提供完整骨架、模型测试适配及管理命令,本地shell和远程console效果不同,默认框架版本自动选择还可能产生差异;flush/reset为数据清理不能误用线上。
本书Helper的manage.py shell操作本地模拟服务,console通过remote_api操作线上;同一段发送邮件代码因此可能从日志模拟变为真实发送。update、rollback、vacuum_indexes和flush又作用于不同对象。执行前辨环境、目标和命令责任,不能因都由manage.py启动就假定都是本地调试。
同名管理工具须先确认运行作用域补充本节结论的独立卡片及原书依据。
框架版本选择要早于首次导入补充本节结论的独立卡片及原书依据。
创建一个Django应用程序
Django项目组合多个app,注册INSTALLED_APPS,URL映射视图,视图返回响应或交模板渲染;模板目录是项目级。本轮不照原文忽略所有警告,也注明clock/code变量误写。
本书Django app含models/views,项目urls把请求送给视图,视图返回HttpResponse或用模板及上下文数据渲染。项目可组合复用多个app,并在INSTALLED_APPS登记;模板路径须相对已配置模板根。原例传clock却一处称code是文字误写,不据此改变量。
视图协调请求模型与模板补充本节结论的独立卡片及原书依据。
在Django中使用App Engine模型
Django可用GAE模型而非原生ORM,Helper BaseModel增fixture适配;Query传模板后迭代才发起数据访问,修改无架构模型也不自动迁移。
视图把db.Query直接交给模板,模板for循环使用迭代接口才获取实体。页面渲染因此包含存储时间、索引错误和潜在额外引用读取,不能认为视图返回前所有数据访问已结束。应按所需数量限制查询,并使渲染阶段的访问范围可控。
模板迭代可能触发存储调用补充本节结论的独立卡片及原书依据。
模型升级不会自动迁移旧实体补充本节结论的独立卡片及原书依据。
使用Django的单元测试和Fixture · 连续片段1
测试执行器按用例初始化、setUp/测试/tearDown运行,fixture提供模拟数据;原文assert_真值说明反向,按测试目的纠正。测试数据应确定,不拿自动时间偶然顺序作稳定依据。
assertEqual验证相等,assertRaises验证指定异常,assert_/assertTrue应在条件为假时失败;原书将最后一项叙述反向,不能照此理解。正常赋值无异常与非法赋值有指定异常是不同测试目标,断言应对应它们,而不是只让测试函数跑完。
断言必须表达预期业务结果补充本节结论的独立卡片及原书依据。
Helper可dumpdata生成JSON,再为测试载入Book和BookReview等实体。夹具应保留引用、预期值和明确排序依据;若依赖连续创建时的auto_now_add顺序,时间相等会使排序断言不稳定,宜固定时间或明确同值次序。准备数据不是直接证明被测逻辑正确。
测试夹具还需稳定身份与排序补充本节结论的独立卡片及原书依据。
测试夹具准备测试所需材料补充本节结论的独立卡片及原书依据。
使用Django的单元测试和Fixture · 连续片段2
每个测试清空模拟库、载fixture、setUp、测试、tearDown;loaddata可手工装载,未实际操作。
测试夹具准备测试所需材料补充本节结论的独立卡片及原书依据。
使用Django表单
djangoforms适配GAE模型构造、绑定、验证和渲染表单;save(commit=False)只产对象,put后才保存再重定向。示例缺目标不存在处理和权限,错误消息叙述前后不同,不直接上线。
BookForm由模型声明生成字段与验证,POST绑定并is_valid后,save(commit=False)只返回对象,随后put才保存。编辑ID还须检查实体存在及当前用户权限,字段类型合格不代表有权修改该对象。示例只展示流程,没有完整访问控制与错误处理,不能直接当成生产入口。
表单验证不等于授权或持久化补充本节结论的独立卡片及原书依据。
表单失败时把已绑定form交回模板,保留输入并附验证错误,成功才保存并重定向。模型可用verbose_name定义标签,日期等字段还须按明确格式解释。原文末段称“没有错误消息”与前面目的矛盾,交付应以实际渲染错误和字段提示验收,不能只看页面重新出现。
无效输入应保留数据并呈现错误补充本节结论的独立卡片及原书依据。
第15章 部署和管理应用程序
第15章把部署从一次上传扩展成版本、共享配置、索引准备和运行观测的组合。新版本先测试,索引Serving后再开放,旧代码回退也要顾及共享数据和任务兼容。日志须读对主机、版本、窗口与保留范围,开发者角色和管理审计另有责任。流量图可按版本切片,预算配额却跨版本汇总;历史控制台、费率和限额不能作为当前平台承诺。
上传应用程序
Launcher/Eclipse或AppCfg可上传,项目根与WAR目录不同;本节重复强调服务端副本不可替代备份,不再重复生成同义操作卡。
上传前核对目录身份与备份补充本节结论的独立卡片及原书依据。
使用版本
同version替换整套文件不改服务数据,新version不自动默认;内部minor不可恢复,需保留可回退的显式版本与构建。图15-1已读,旧请求并存边界仍适用。
本书同version上传会替换该版本全部文件,内部minor无法自行访问或恢复,数据库、缓存与已排任务却不随文件替换回滚。较大变更应保留独立版本、先测试再切默认,并另设计数据兼容与逆向方案;“可切旧代码”不等于业务状态一同回到过去。
显式保留版本才有回退目标补充本节结论的独立卡片及原书依据。
非默认版本也需要访问控制补充本节结论的独立卡片及原书依据。
管理索引
新索引Building完成Serving前查询可能失败,先准备索引再放量;Error需回到数据/索引设计修复。vacuum清理最新配置未列自定义索引,需保护旧版本依赖。图15-2已读。
索引配置上传后还需扫描已有实体建立内容,Building不等于Serving。若旧默认代码将原地替换,应先单独建索引;若先上传新非默认版,则等待所需索引Serving再切默认。Error要检查索引组合与实体数据,不能只重复上传盼自动成功。
索引可服务后再开放依赖代码补充本节结论的独立卡片及原书依据。
本书移除配置不会立即删线上旧索引,vacuum_indexes才按最新配置清理未列出的自定义索引。清理前列出仍在服务及可回退版本所需形状,避免新配置只覆盖当前分支就删掉旧代码依赖;回收存储与保留回退能力须同时考虑。
清理索引前核对所有活动版本补充本节结论的独立卡片及原书依据。
浏览和下载日志
日志可按版本、主机、级别和时间筛选并下载,默认导出不含Host;默认域跨代码切换难区分,应记发布身份。保留窗口有限且append依赖本地末尾,历史90天等不作现行承诺。图15-3已读,severity数字不一致不照抄。
控制台按所选应用版本显示,导出可用include_vhost/vhost补充或限制主机;默认域在代码切换前后可能同名,因此应把发布身份写入应用日志。读取请求、状态、资源与关联消息时同时标明时间范围和级别,避免从部分筛选结果推断全部流量。
日志查询先确认版本主机与窗口补充本节结论的独立卡片及原书依据。
request_logs的append可根据本地最新日志接着下载,但服务器只保留有限范围,下载频率过低仍会丢掉已过期数据。归档应验证时间连续性、缺口和本地文件状态;导出成功只说明拿到当前可用部分,不证明过去全部请求均在其中。具体保留量和severity编码按实际SDK核对。
增量日志归档不能忽略保留窗口补充本节结论的独立卡片及原书依据。
监控数据存储区
线上Data Viewer可查改有限实体结构并受已有索引约束,监控工具不是完整迁移器,Java应用同样能在控制台用GQL而不表示JavaAPI支持GQL。
本书线上Data Viewer可对Java应用数据执行GQL,不表示Java存储API也接受GQL。控制台仍需已有索引,且编辑不能随意新增属性、改类型或处理Blob。确认工具作用域与限制后再用于排障,不将有限编辑器当架构迁移或完整数据验证通道。
控制台查询能力与代码API分开补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
管理开发人员
历史开发人员均有广权限,Pending邀请不等于Active;接纳与移除是权限操作,Admin Logs单独记录管理行为。
本书开发人员可部署、改版本、读写数据、管理其他开发者甚至删除应用;Pending只是邀请待接受,Active才生效。不能只为查看一份日志或发邮件就默认授予这种角色,需按目标平台的真实权限模型选择最小必要访问并保留管理审计。历史同权模型不当当前IAM规则。
开发者邀请是广权限授予补充本节结论的独立卡片及原书依据。
请求日志连接延时资源与错误补充本节结论的独立卡片及原书依据。
配额与付费
仪表板时间图按代码版本,资源预算及配额却全应用共享;观察错误与拒绝时须辨固定限制和可付费资源。图15-4已读,所有价格和支付流程保持历史范围。
本书请求曲线和URL列表可按版本查看,资源用量与预算却汇总所有版本。一个版本流量下降不说明全应用还有足够配额,应同时看固定API限制、服务带宽及预算消耗。历史充值/授权和价格不作当前财务建议,实际资源单位也须分别核对。
版本流量与共享配额不能混读补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
获得帮助
官方文档、SDK样例/源码、状态页及问题跟踪各回答不同问题,旧网址仅留历史入口,SDK内部未支持功能不升格公开契约。
SDK源码与测试可解释实际行为,官方API文档说明受支持接口,状态页和维护通知反映服务事件,问题跟踪承接缺陷报告。发现源码内部扩展不代表平台承诺长期支持;核验时标明提交、文档版本和观察范围,不能把一份历史实现当所有时期保证。
源码线索不能升格支持契约补充本节结论的独立卡片及原书依据。
原书依据 · 1 处
作者与封面说明
作者履历与封面动物介绍均已完整读取,分别用于身份背景和装帧说明;不作为GAE技术推理依据。
作者介绍
作者介绍完整读完,作为Dan Sanderson身份背景保留,不把从业履历变成GAE技术机制或现实职业建议。
封面介绍
封面介绍完整读完,叙述waterbuck的形态、栖息与行为,是装帧说明;未纳入本书云平台技术知识主线,不跨领域扩写动物学卡片。
跨章综合
本书反复处理的是责任边界。应用实例负责一次请求的计算,前端负责路由与部分访问约束,持久层保存业务状态;框架和对象模型负责组织代码与验证,但不能改变底层存储允许的查询和事务范围。看懂接口之后,还要问状态由谁拥有、何时生效、失败会怎样表达。
读取速度来自预先建立的结构。索引把常见查询形状变成连续范围,多值成员和复合列又决定索引条目数量;缓存把可重建副本留在易失介质中,实例复用则保留可共享初始化结果。这几种机制共同减少重复工作,却承担不同正确性责任:索引资格决定哪些实体可见,缓存可能旧或缺失,实例内存也不保证跨请求亲和。
原子性、重试和幂等不是同义词。实体组事务保护一组本地读改写,但外部邮件、缓存和其他组不会随之回滚。队列至少一次执行使工作更易恢复,却会再次调用已做过的动作;金币转账因此需要持久业务身份、同组去重与后续对账。事务入队保证后续工作随源提交记录下来,不保证跨组状态同时变化。
部署也有同样的分层。代码版本便于测试和回退,后台数据、索引、队列和配额却共享;索引配置上传后还要等可服务,旧在途请求和旧任务载荷也可能继续出现。因此回退代码不等于回退业务状态,测试版本可访问不等于数据或权限已隔离。
最后,观察和证据必须对应所声称的事实。本地模拟、dry-run、请求返回、消息入队、提交成功与最终业务完成分别提供不同保证。日志的版本、窗口和单位,源码的提交及文档的契约,都应明确。书中有若干文字/代码不一致和历史实现差异,本轮将它们保留在对应位置并限缩结论,不把旧平台示例当成当前部署指南。
发散与实践
读者延伸:先通过已开始的缓存API源码对照,练习把返回值、异常与业务效果分开;再把批量工具的预演和恢复观念迁移到本轮笔记导入,对内容、身份与定位投影逐项对账。两张实践卡交付的是有边界的计划,第一张附已填写首轮映射,第二张的实际执行证据随工作流后续阶段记录;不把计划生成等同完整实验已经完成。